NARROW

AI can start the work. NARROW helps make sure the work is finished safely.

NARROW is a local-first task continuity and completion supervisor for AI coding agents. See the concise project profile for its purpose, intended users, operating model, and maturity. It combines explicit task contracts, isolated Git copies, provider-native execution, compact cross-session memory, live scope monitoring, bounded repair cycles, evidence-based verification, and a local Control Center.

It works with the coding agents you already have. NARROW itself does not require an API key or upload source code to a NARROW service. Provider authentication and usage remain with the provider's own CLI and account.

Alpha software. NARROW is a supervisor and evidence recorder, not a guarantee that an agent is safe or that a change is correct. Read SECURITY.md and the threat model before using it on valuable repositories.

What's new in v0.5.0

• Single-flight task execution: NARROW rejects a second agent, repair loop, verification, or finish operation while the same task already has an execution lease.
• Inherited lease handle: the first-level agent/check receives the lock handle. On POSIX, the lease remains held if NARROW exits unexpectedly while that child remains alive.
• Public source tree: source, tests, and documentation are checked in at the repository root; CI builds and tests an exact-commit source archive for each validated release candidate.

This is coordination, not a machine sandbox. Detached descendants may outlive their parent process, and the Windows crash-lifetime path still needs dedicated validation. See the v0.5 release notes.

What's new in v0.4.0

• Local Control Center: responsive, read-only dashboard at 127.0.0.1, with task state, scope summary, acceptance progress, current/stale checks, and a sanitized activity timeline.
• Task portfolio: narrow tasks lists active work; narrow tasks --all --json emits a bounded, sanitized task index.
• Model effort controls: --effort low|medium|high|xhigh for Claude Code and Codex CLI, plus Claude-only max where the selected model/account supports it. Provider model support remains authoritative.
• Richer Claude telemetry: optional Task/Agent tools, task-created/completed and subagent lifecycle hooks, and tool-failure metadata. Subagents require explicit --allow-subagents opt-in.
• Compatibility diagnostics: opt-in provider version probing reports when Claude Code should be upgraded for full task/subagent telemetry.

Core workflow

1. Define the task. State the objective, allowed paths, denied paths, and acceptance criteria.
2. Create an isolated Git copy. The original checkout remains untouched by normal agent editing.
3. Run an agent. Use Claude Code, Codex CLI, or a configured generic command adapter.
4. Watch scope. NARROW records file changes and uses provider hooks where available to block selected out-of-scope direct file operations.
5. Preserve continuity. Decisions, progress notes, failures, verification results, and provider session IDs remain in a local SQLite journal. A compact handoff can resume work in a fresh session or another provider.
6. Verify and repair. Explicitly configured checks run under a bounded repair budget. A failure can trigger a limited repair attempt; repeated failure becomes a blocked/review state.
7. Require human acceptance. NARROW does not equate an agent saying “done” or a green test with semantic correctness. A human reviews the diff and confirms acceptance criteria before finish can mark the task verified.

Install

Requirements: Python 3.11+, Git, and a supported local agent CLI for native provider execution.

Clone the public source checkout, then install it locally:

git clone https://github.com/ahmedfayedesmail-ui/narrow-ai.git
cd narrow-ai
python -m pip install .
narrow --version

The current source release is tagged v0.5.1. This is a packaging and documentation refresh of the v0.5.0 Alpha; it does not change runtime behavior. See the v0.5.1 release notes and the Python publishing guide.

For a reproducible source install:

git clone https://github.com/ahmedfayedesmail-ui/narrow-ai.git
cd narrow-ai
git checkout v0.5.1
python -m pip install .
narrow --version

After the package has been published to the index you use, install it with python -m pip install narrow-ai.

For development and tests:

python -m pip install -e '.[dev]'
python -m unittest discover -s tests -v

Start a task

Run these commands from the original project checkout:

narrow init
narrow start \
  --title "Improve checkout reliability" \
  --goal "Fix the retry behavior without changing the public API." \
  --allow "src/checkout/**" \
  --allow "tests/checkout/**" \
  --deny "src/checkout/secrets/**" \
  --accept "A retryable timeout is retried at most twice." \
  --accept "The public API and successful checkout behavior remain unchanged."

Edit .narrow/config.json and define at least one reviewed verification command. Checks are argv arrays, not shell strings. Example:

{
  "checks": {
    "unit": {
      "command": ["python", "-m", "pytest", "tests/checkout", "-q"],
      "timeout_seconds": 300
    }
  },
  "max_repair_attempts": 2
}

Review every configured command before approving it. Verification commands run with your user permissions inside the task copy. They are not sandboxed by NARROW.

Run a native agent

First, install and authenticate the provider CLI yourself. NARROW never asks for provider credentials.

narrow providers --versions
narrow doctor --versions

# Claude Code (use a reasoning effort supported by the selected model)
narrow drive --provider claude --effort xhigh --max-attempts 2

# Codex CLI
narrow drive --provider codex --effort high --max-attempts 2

To explicitly enable Claude Agent/task tools and subagents:

narrow drive --provider claude --allow-subagents --effort xhigh

# Higher-autonomy Claude dynamic workflows (requires subagents opt-in)
narrow drive --provider claude --allow-subagents --ultracode

Subagents share the task workspace and the same user-level process permissions. This option is off by default. It does not create a separate sandbox for each subagent. --ultracode is a separate opt-in to Claude Code's dynamic multi-agent workflow mode; it requires --allow-subagents, uses the provider's ultracode mode, and cannot be combined with --effort. Model/account support remains provider-controlled. Claude effort levels are model/account dependent; Codex reasoning effort is also model dependent. Omit --effort to use the provider's own default.

--max-budget-usd is a Claude CLI client-side estimate/cap, not a billing guarantee. Codex has no NARROW-compatible per-run USD cap in this release; use the provider's own usage controls.

Continue work across sessions

narrow tasks
narrow status --task <task-id>
narrow handoff --task <task-id>
narrow resume --task <task-id>

A handoff is generated from recorded task state, decisions, progress, changes, and evidence. It is deliberately not a full transcript. Only information explicitly recorded in NARROW can be reliably carried forward.

Inspect, accept, and finish

narrow inspect --task <task-id>
narrow note --task <task-id> "The failing integration test is caused by the stale token fixture."
narrow decision --task <task-id> "Keep the public response schema unchanged."
narrow verify --task <task-id> --check unit
narrow accept --task <task-id> --criterion 1 --evidence "Reviewed retry test output and implementation diff."
narrow report --task <task-id> --format markdown --output work-receipt.md
narrow finish --task <task-id>

A check result is snapshot-bound. Any subsequent workspace change makes the earlier result stale. Completion requires current passing configured checks, human-confirmed acceptance criteria, a safe workspace, and an unchanged original checkout.

The exact review procedure matters: Human review and acceptance explains how to inspect the isolated diff and every untracked file, record criterion-by-criterion evidence, and complete the final gate. NARROW records the user's assertion; it cannot prove that a human actually read the code.

Reproducible end-to-end demo

The local demo exercises the actual CLI in a disposable temporary Git repository. It shows a failing check followed by a bounded repair/handoff, and a separate scenario that stops at NEEDS_REVIEW. It uses a deterministic fake agent—not Claude/Codex—and deliberately leaves the final human acceptance step to the user.

PYTHONPATH=src python examples/demo.py --scenario repaired
PYTHONPATH=src python examples/demo.py --scenario blocked

Local Control Center

Start the read-only dashboard from the original repository:

narrow dashboard

Open http://127.0.0.1:8765. It binds to loopback only, has no remote assets or telemetry, exposes read-only JSON endpoints, and does not return raw notes, prompts, tool outputs, or check logs. It refreshes automatically. Stop it with Ctrl+C.

Supported providers

The adapters use documented CLI interfaces, not private transcript or database formats. Actual authenticated end-to-end behavior still needs validation against the exact provider CLI and model installed on the user's machine. See provider details.

Which execution mode should I use?

For native provider safeguards, use narrow drive --provider ...; do not assume narrow run -- claude is equivalent. See the complete threat model.

Safety boundaries — read before use

• Each task is a separate Git copy without remotes. The source checkout is not edited by normal NARROW agent execution.
• A Git copy is not an operating-system sandbox. Processes launched by NARROW generally inherit the invoking user's OS permissions.
• Claude's required sandbox applies to its shell commands and children; Claude documents that some other tool/helper activity runs outside this shell boundary. NARROW adds direct-file hooks for a limited documented tool set, not a universal filesystem monitor.
• Codex uses its own workspace-write sandbox. NARROW does not bypass provider approvals or sandbox controls.
• Configured verification commands are executable programs. They may have side effects and run with the user's permissions. Review them before approval.
• Never use unattended mode on untrusted repositories, agents, prompts, hooks, plugins, or checks. Use a disposable container/VM with restricted mounts, network, credentials, resources, and process permissions for stronger isolation.
• NARROW does not automatically commit, merge, push, publish, deploy, delete, or integrate changes.
• A model's output, test success, or generated report is not independent proof of correctness. A human must review the actual changes.

See the safety model, the threat model, the security policy, and the human-review procedure.

Current validation

• The local unit suite covers the CLI, task creation, path/snapshot gates, provider adapters with fakes, dashboard, bounded repair/handoff, and task locks.
• The published v0.5.0 release commit 5eb6a469c5c0317e2b9528dc2dcbfafd0fae5228 passed all eight CI jobs in run #41650780275: Ubuntu/Python 3.11–3.14, macOS/Python 3.13, Windows Server 2025 repaired/blocked demo workflows, and wheel/sdist build plus clean wheel installation.
• The current main commit 2d01a35ab43aef5775b80790fefb830abe59305e also passed all eight jobs in run #41651845855. This follow-up changes documentation only; the published application source and version remain unchanged.
• The owner-confirmed GitHub release publisher completed successfully in workflow run #41651002381, creating the v0.5.0 Alpha prerelease from the release commit. These CI results are not authenticated provider sessions or an independent security review.
• The run also created, extracted, and tested a source archive from the exact checked-out commit; the tested archive is attached to the workflow run as an artifact. GitHub's Download ZIP is the current-source download route.
• The deterministic demo exercises successful repair and bounded failure with a fake agent. It is not an authenticated provider test.
• Authenticated Claude/Codex end-to-end sessions, provider-version support guarantees, Windows inherited-handle crash lifetime, full OS-sandbox escape testing, and independent security review remain open gates.
• Android/Termux is not a supported or validated platform claim.

Contributing

Read CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md. Safety regressions, privacy leakage, and unbounded execution are release blockers.

License

MIT — see LICENSE.