SCOPE

A governed, scoped, approval-gated coding agent — in your terminal.

SCOPE turns a plain-English intent into a reviewed pull request. Every run flows plan → policy gate → execute → verify → review → integrate, with cost control, scope enforcement, and a secret-before-PR security gate at every step. The agent edits only files inside an approved scope; TypeScript holds git/commit authority and budget enforcement, while a Python agent loop does the actual code changes.

Published on npm as scope-agent; the command is scope.

Install

npm i -g scope-agent     # Node >= 22
scope --version

The published CLI points at the hosted control plane by default (https://agisflow-production.up.railway.app) — no config needed to start.

Quick start

# Draft a deterministic, zero-token plan for an intent (offline, no run):
scope plan "add a CONTRIBUTING.md with contribution guidelines" --repo owner/name

# Start a real governed run (opens a draft PR on success):
scope run "add a CONTRIBUTING.md with contribution guidelines" \
  --repo owner/name --model economy --approve

# Open the conversational TUI:
scope chat

run prints live progress — plan, the approval gate, agent edits, checks, review verdict, and the PR URL.

Commands

| Command | What it does | |---|---| | scope run <intent> | Start a governed run → reviewed draft PR | | scope chat | Full-screen conversational TUI | | scope plan <intent> | Zero-token deterministic plan (offline) | | scope search <query> | Repo search — lexical (BM25), semantic, or hybrid (0 tokens) | | scope index | Print the structural index of the current repo (0 tokens) | | scope export <kind> <intent> | Export a plan / index / PR package — file, PDF, or integration | | scope integrations <action> | Integration adapter status / connectivity test | | scope models | List local Ollama models and pick one for the session | | scope auth | Manage credentials (~/.scope/credentials) | | scope ws | Multi-repo workspace (.scope/workspace.yaml) | | scope open <path> | Editor deep links for a path (optionally launch $EDITOR) |

run options

| Flag | Default | Notes | |---|---|---| | --repo <owner/name> | — | Target GitHub repository | | --base-sha <sha> | main | Base branch or commit | | --model <profile> | balanced | economy | balanced | quality | | --mode <profile> | balanced | strict | balanced | permissive policy mode | | --budget <usd> | 10 | Run cost ceiling | | --approve | off | Pre-clear the source-code execution gate (non-interactive) | | --output <format> | text | text | json | stream-json |

How a run works

intent → plan (task graph) → POLICY GATE (approval) → isolated sandbox
  → agent edits files within approved scope → checks/tests → security scan
  → reviewer verdict → git push branch → open draft PR (with evidence)

• Scope enforcement — the agent can only read/write files matching the approved scope globs; path-escape attempts are blocked in the tool layer.
• Approval gate — source-code changes require an explicit decision before execution (docs-only can auto-approve). Use --approve to pre-clear it.
• Budget — runs are capped by --budget and an org-level ceiling.
• Security — a high-confidence secret in changed files blocks integration (no branch with a leaked secret is ever pushed).
• Evidence — every run produces an auditable bundle (plan, diff, checks, review, cost) retrievable via GET /v1/runs/:id/audit.

Configuration

| Variable / flag | Purpose | |---|---| | --api-url <url> / AEGIS_API_URL | Point the CLI at a different control plane (self-hosted backend or staging) | | ~/.scope/credentials | Local credential store (scope auth), chmod 600, never echoed |

Private repos & opening PRs are performed server-side by the control plane using its configured GitHub credentials. To operate on your own private repositories with your own token, self-host the backend (below) or use a deployment whose GitHub App/token has access.

Self-hosting the backend

SCOPE is a pnpm/TypeScript monorepo with a Python agent. It runs credential-free in dev (deterministic provider, in-memory persistence/sandbox) and swaps in real providers via env vars.

pnpm install
pnpm check                 # lint + typecheck + test (the gate)
pnpm start:api             # control plane on 127.0.0.1:4317
scope --api-url http://127.0.0.1:4317 run "..." --repo owner/name

Production deploy (Railway + Neon Postgres/pgvector + Cloudflare R2 + OpenRouter) is documented in docs/deployment-runbook.md. Key env flags: AEGIS_PROVIDER (deterministic/openrouter/anthropic/openai/ollama), AEGIS_PERSISTENCE (memory/postgres), AEGIS_ARTIFACT_STORE (memory/s3), provider-specific model + price vars, GITHUB_TOKEN/GITHUB_APP_*. Full reference in .env.example.

Local models (free)

ollama pull qwen2.5-coder
AEGIS_PROVIDER=ollama OLLAMA_MODEL=qwen2.5-coder pnpm start:api

Architecture (one line)

TypeScript control plane (API, governance, persistence, TUI) + a stdlib-Python agent loop spawned as a subprocess. The boundary: Python edits files within the approved scope; TypeScript owns git/commit authority, evidence, and budget. See CLAUDE.md and AGENTS.md for engineering rules.

License

Proprietary — all rights reserved (update as appropriate).