Narrowbit

Website: narrowbit.dev · early 0.1 preview

A local, context-managed coding agent for your Mac. It plans, reads, edits, runs commands and verifies, keeping a durable local log of everything it does, so a model only ever sees the small slice of context it needs for the next step.

Goal metric: correct coding work per unit of AI usage, not just fewer tokens.

• Bring your own model. Claude (your Claude subscription), Codex (your ChatGPT subscription), Antigravity (your Google account), or any OpenAI-compatible API: OpenRouter, Groq, Gemini, OpenAI, DeepSeek, Ollama, Ollama Cloud, LM Studio and others. Three model slots (explore / execute / escalate) exist for mixing models, but measurement found a single good model in all three usually wins — see "What is and isn't proven".
• Point it at a file. @path/to/file in a task reads that file straight into context instead of costing a search turn; attach images or PDFs (Claude, Codex, vision-capable API models) for UI bugs or specs.
• Rewind. A checkpoint is taken before a task starts and after every edit; undo any of them without touching your commit history. Files created since the checkpoint are moved to .narrowbit/rewind-trash/ rather than deleted, and files you have staged are left alone.
• Local-first. No telemetry, no repo upload. Selected code and context go to the model provider you choose on every call, the same as typing it into that provider yourself; the app also checks GitHub for updates, and any connectors you configure make their own calls. Known secret patterns and labelled credentials are redacted from what the agent stores or re-reads (best effort: an unlabelled opaque string cannot be recognised; see SECURITY.md).
• You stay in control. Commands ask for approval, edits show as diffs, and nothing is committed until you say so. "Done" is checked against your repo's own verify commands.
• Extensible. Reusable skills (task templates) and connectors (any MCP server, e.g. GitHub) the agent can call.

Status: early (0.1). Expect rough edges. See "What is and isn't proven" below.

Install

macOS. The installer checks what you have, asks before installing anything missing (Homebrew, Node), clones this repo to ~/Narrowbit, builds it, puts narrowbit on your PATH and builds the native app:

git clone https://github.com/sanjuraw/narrowbit.git ~/Narrowbit && ~/Narrowbit/scripts/install.sh

Run scripts/install.sh --check first to only see what's missing. The app is installed to /Applications/Narrowbit.app (or ~/Applications if your account cannot write to /Applications). If narrowbit ends up off your PATH (npm's global folder isn't always on it), the installer says so and prints the line to add. It can't sign in for you: to use Claude run claude auth login (or codex login, or add a free API key); the app's "get a model ready" card and narrowbit doctor show what's left.

Manual install: Node ≥ 22.13, then npm install && npm run build && npm link && scripts/build-mac-app.sh --install.

Then in any project folder: narrowbit init, and either narrowbit ui (browser/app) or narrowbit agent "fix the failing test in src/foo.ts".

Updating: the app checks GitHub on launch (and every few hours) and shows an Update available banner; Update now fast-forwards the checkout, reinstalls if dependencies changed, rebuilds (rolling back if the build fails) and restarts. It refuses to touch a copy with uncommitted edits or local-only commits, and only the account that owns the folder can update it. Manual equivalent: git pull --ff-only && npm install && npm run build, then reopen the app.

Using it

Built-in skills (in every project's Skills list; click one to drop it into the message box, or narrowbit agent --skill "bug fix" "<what's wrong>"): Bug fix (root cause, reproduce, smallest fix, verify), Code review (correctness, security, tests; changes nothing), Write tests, Refactor (pin behaviour first, small verified steps), Explain this code (read-only walkthrough), Plan a project (risks, phases, a cheap test each; for the planning chat), Research a repository (read it properly, say what was not read), Add a feature (copy the nearest pattern, with tests), Fix a failing CI run, Write a pull request, Update dependencies (one at a time, checks after each), Write documentation (run what you document), Careful changes (say your assumptions, smallest change, touch only what was asked, define the check first; after the habits described in Andrej Karpathy's notes on LLM coding mistakes) and Security review. Save a skill with the same name to override one; add your own with the + next to Skills.

narrowbit agent "<task>" [--provider claude|codex|openrouter|...] [--skill "<name>"] [--boss] [--max-steps N]
narrowbit models choose                # pick provider + the three model slots (saved per repo)
narrowbit keys set <provider>          # API key, stored in ~/.narrowbit/keys.json (0600)
narrowbit skills add "Bug Fix" "Reproduce with a failing test, fix the code not the test, verify."
narrowbit connectors add github --env GITHUB_TOKEN=... -- npx -y @modelcontextprotocol/server-github
narrowbit limits                       # Claude / Codex 5-hour and weekly usage

narrowbit agent edits your working tree directly and refuses to start on a dirty tree unless you pass --force. Review the diff before committing.

What is and isn't proven

Every result below names its baseline and how much it rests on. Tasks are real fixes mined from a project's history: start at the commit before the fix with the fix's own tests added (so they fail), and succeed when those tests pass without the agent touching them. The full log, including what did not work, is in docs/history.md.

Hono (TypeScript), all 40 tasks, against native Claude Code, both on Claude Sonnet (history entries 61-63):

	Native Claude Code	Narrowbit
Tasks solved	40 / 40	40 / 40
Cost for all 40	$3.48	$1.43 (−59%)
Uncached input per task (median)	—	−61%
Turns per task	7.1	5.2
Task time, median	16 s	19 s (slower)
Task time, slowest 10%	28 s	28 s

Limits: one repository · one try per task · one model · native measured once on the same day, not repeated · public code the model may have seen · subscription cost is notional (nothing is billed per token) · measured before Claude's structured output became the default, which in a same-run A/B solved 40/40 instead of 39/40 for about 8% more cost.

click (Python), all 43 tasks, against native Claude Code, both on Claude Sonnet (history entries 67-68):

	Native Claude Code	Narrowbit
Tasks solved	43 / 43	43 / 43
Cost for all 43	$5.05	$3.07 (−39%)
Uncached input per task (median)	—	−51%
Turns per task	9.3	8.0
Task time, median	25 s	36 s (slower)

Limits: as above, plus Narrowbit's run happened about four hours after native's. Before Claude's replies went through structured output, Narrowbit solved 39 of 42 here; two of its three failures were replies stuck in a loop.

Other providers, same 40 Hono tasks: Codex (gpt-6-sol) 40/40; DeepSeek V4.1 Flash through its API 39/40, about $0.22 for all 40 at list prices. Antigravity and free API models worked but used 2-3× the tokens, and free models solved about 6-7 of 10.

What did not work:

• Narrowbit is not faster than native Claude Code; at best it matches it.
• Mixing models (a cheap one reading, an expensive one editing) lost to one good model doing the whole task, both times measured. A cheap model scouting in its own conversation helped once (Claude's cost −57% on 10 tasks), unconfirmed at scale.
• Project memory notes showed no reliable token saving on single-file fixes.

Not proven: other languages and project sizes beyond these, the API adapters beyond DeepSeek, and parallel multi-agent work (untried).

Run the numbers yourself: see "Benchmarking" below.

Security

• Every project gets a checkpoint. narrowbit audit (no model, nothing leaves your machine) finds committed secrets, .env files git would commit, and secrets given browser-exposed prefixes; it also runs gitleaks over history if installed. The app runs the same scan when you click Commit and pauses if it finds credentials. The built-in Security review skill asks the agent for the judgement-based checks: access control, data handling, input handling, production hygiene.
• The agent asks before running commands (in the app and in the terminal; --allow-commands opts out), and its file access is confined to the project folder, symlinks included.
• Connectors run commands you configure, like any MCP client; their environment variables (often tokens) are stored in ~/.narrowbit/connectors.json (mode 0600) and never sent to the app page. Only add servers you trust.
• Updates trust the repository: the update button runs npm install and a build on whatever is on GitHub main. Keep the repo's owners on two-factor authentication.
• Codex's exec and Antigravity's agy don't fully disable their own tools by flag: Codex is sandboxed and its own tool features are switched off; Antigravity runs under a lean custom agent with one inert tool. Claude runs fully tool-free.
• Report vulnerabilities privately (see SECURITY.md).

Contributing

Issues and PRs welcome. npm test and npm run test:ui must pass; none call a model. Read CLAUDE.md first (architecture, rules, current state), and docs/history.md for what was tried and failed, so you don't repeat it. A working rule of this project: every automatic feature needs a measured reason to exist.

Command reference (context tools, also usable standalone)

init, index [--force], status	incremental index (mtime/size fast-path, then content hash)
task "<text>" [--budget N] [--print] [--json] [--error-file f]	compile a context package
inspect, context, expand, close [--success|--failure]	explain selection, show the package, get more context, record the outcome
symbol, refs, outline, search, grep, tests	deterministic lookups (also exposed over MCP as nb_* tools)
run -- <cmd>	run a command, get compressed output; raw log kept in .narrowbit/logs
verify [--full]	type-check + lint + tests focused on changed files, failures only
memory add <type> "<text>" …	decisions, constraints, conventions, facts, failed approaches, as Markdown in .narrowbit/memory
train, eval	learn / measure file-ranking weights from git history (local, no model calls)
benchmark init | run <file> | report	paired A/B benchmarks
claude "<task>", install claude	the older Claude Code sidecar mode (MCP tools + hook)

Context selection (src/ranker.ts, src/package.ts)

Used by narrowbit task/claude and by the agent's search; the agent runtime itself does not inject a predicted package (see docs/history.md for why).

The ranker scores files with rule-based signals. The weights are in WEIGHTS and meant to be tuned with eval and benchmark:

• BM25 over identifier sub-words, comments and path segments, with morphological expansion (verification↔verify)
• exact symbol names mentioned in the task
• fuzzy matches against symbol names
• mentioned paths, and module names (e.g. "trie router" → router/trie-router/)
• stack-frame locations, including the enclosing function
• project memory
• git dirty/recency, which only amplifies existing evidence and ignores bulk commits
• import-graph propagation from seed files
• callers of seed symbols
• penalties for tests, docs, config and generated files

The package is then filled progressively up to the budget, 8k by default:

1. small files in full
2. otherwise the matching functions (by name, or by body vocabulary for large files) plus a file outline
3. outlines for secondary files
4. path-only candidates

It also includes related tests with the focused-test command, the relevant git state and relevant memory. A confidence label (high, medium or low) tells the agent when to treat the selection as hints.

Text the agent stores or re-reads passes through a pattern-based secret redactor (best effort, see SECURITY.md). .env*, keys and credentials are never indexed.

Benchmarking

Build a task set from a repository's own history (no model calls):

node scripts/build-tasks.mjs --repo ../hono --out bench-hono.json --max 40 --verify-each --setup "npm ci"

Python repositories work too (pytest, through the repo's .venv when it has one); --setup runs in each worktree, for example to create that .venv.

Each commit that changed source and its tests becomes a task: the agent starts at the parent commit with the commit's tests already applied (so they fail) and must make them pass without touching the tests. --verify-each proves every task is winnable by checking fail→pass with the real fix. Add --with-body to include the commit body in the prompt (usually explains the fix, so off by default).

narrowbit benchmark init            # or hand-write benchmark.json
narrowbit benchmark run benchmark.json --dry-run
narrowbit benchmark run benchmark.json
narrowbit benchmark report

• Isolation: each task × arm runs claude -p --output-format stream-json in a fresh git worktree at the same commit, with --strict-mcp-config so the user's other MCP servers don't skew either arm, and with arm order alternated between tasks.
• Recorded per run: success (the verify command's exit code), input, cache-creation, cache-read and output tokens, cost, turns, tool calls, files read and searches.
• Report: the north-star metric (successful tasks per million input tokens) and paired reductions. It gives the brief's GO/NO-GO verdict only once n ≥ 30 tasks.

Add a "context hygiene" baseline arm via arms[].appendSystemPrompt to compare against a tuned native setup. Check that the native arm can actually run the tests: its commands are limited to claudeArgs' allow list, and a test command missing from it quietly turns the run into an unfair comparison.

Memory

Markdown notes with frontmatter, one per entry, in .narrowbit/memory/<type>s/ (decisions, constraints, failures, …). Open that folder as an Obsidian vault to browse and edit it; hand-written notes are picked up too. To also read notes you already keep elsewhere, add folders to memoryDirs in .narrowbit/config.json; these are read-only. Retrieval is deterministic keyword/file overlap, with no model calls. V0 JSON memory migrates automatically.

Ideas borrowed (MIT-licensed projects; ideas only, no code copied)

• jcode: grep results that carry file structure → nb_grep (matches tagged with the enclosing function).
• 9router (RTK): lossless, fail-safe compression of tool output → git diff and grep condensers, plus a guard that never returns something larger than the raw output.
• Claude Code: old tool output is the first thing to go when context fills, so Narrowbit keeps tool results small up front; the hook sends deltas only, to stay friendly to prompt caching.

Layout

src/ holds the modules; CLAUDE.md has the full, current module table. Highlights: runtime.ts (the agent loop), providers/ (model adapters), ui.ts + ui-page.ts (the app), skills.ts, connectors.ts + mcpClient.ts, and the index/ranker/query modules from the original context engine. mac/ is the SwiftPM native window. test/ has a fixture generator and the suite: npm test.

Requires Node ≥ 22.13 (for node:sqlite). Runtime dependency: typescript only.

More things it can do

• Side by side. Split view (the ◫ button, or ◫ on a session in the sidebar to open that one beside) shows a second conversation next to the first in the same window; each has its own project and its own task. A separate window (⧉, or Window > New Window, ⌘N, in the Mac app) works the same way. Several tasks already ran at once (up to four, in separate copies when they share a folder).
• Link reader. Paste a link into the planning chat and Narrowbit reads the page for the model (a GitHub repository: its README and file list). Public web only, no logins, size and time limits, secrets scrubbed, shown above the reply as "Read …" or "Couldn't read … — why". Not yet in task conversations inside a project. Coding tasks in the app read links in their messages the same way.
• Web search in the planning chat. Research questions ("what's on the market?") use the search of the model you picked: Claude's WebSearch and WebFetch, Codex's live web search, Antigravity's search_web. API models have none and say so. Only the planning chat; the coding loop never gets web tools.
• The planning chat knows your project. With a project open it lists your skills (and the built-in ones), sends the full text of a skill you name, and brings in matching notes from the project's memory. A linked GitHub repository comes with its README, file list and a few key files. It can also suggest notes to keep (decisions, constraints, facts); nothing is saved until you press Save.
• Explore a linked repository. Paste a public GitHub link into the planning chat and Narrowbit makes a read-only copy that Claude or Antigravity can browse with their own file tools (read, list, search), fenced to that copy. Codex and API models only get the README, file list and key files.
• Hooks. narrowbit hooks set afterEdit "npx prettier --write \"$NARROWBIT_FILE\"" runs your own command after each edit the agent applies; afterTask runs when a task ends (with $NARROWBIT_OUTCOME). 30 second limit, a failing hook never stops the task, and the agent is told when a hook failed or rewrote the file it just edited. A hook that a repository ships in its own settings only runs once you have accepted it.
• Scheduled tasks. narrowbit schedule add nightly --task "Run the tests and fix what failed" --every day --at 02:00. Every run is unattended and careful: a separate copy of the project (nothing in your folder changes until you press Apply), only the project's own checks and read-only commands, nothing in a project you haven't trusted. The app runs due schedules while it is open; narrowbit schedule install adds a macOS timer (launchd, every 10 minutes) so they also run when it is closed, narrowbit schedule uninstall removes it. Listed, with a "Run now" button, under Models & settings.