{"id":49527396,"url":"https://github.com/phonton-dev/phonton-cli","last_synced_at":"2026-05-22T06:17:15.567Z","repository":{"id":355055280,"uuid":"1225611578","full_name":"phonton-dev/phonton-cli","owner":"phonton-dev","description":"Open-source Phonton CLI: a local-first agentic development terminal with context packs, source handles, and verification gates.","archived":false,"fork":false,"pushed_at":"2026-05-11T21:25:07.000Z","size":10223,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-11T23:39:14.892Z","etag":null,"topics":["agent","agentic-ai","agents","ai","ai-coding","byok","cli","code-generation","code-review","coding-agent","developer-tools","local-first","open-source","ratatui","repo-context","rust","semantic-search","terminal","tui","verification"],"latest_commit_sha":null,"homepage":"https://www.phonton.dev/cli/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/phonton-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-APACHE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-30T13:07:46.000Z","updated_at":"2026-05-11T21:25:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/phonton-dev/phonton-cli","commit_stats":null,"previous_names":["phonton-dev/phonton-cli"],"tags_count":47,"template":false,"template_full_name":null,"purl":"pkg:github/phonton-dev/phonton-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phonton-dev%2Fphonton-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phonton-dev%2Fphonton-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phonton-dev%2Fphonton-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phonton-dev%2Fphonton-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phonton-dev","download_url":"https://codeload.github.com/phonton-dev/phonton-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phonton-dev%2Fphonton-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33092637,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-16T04:41:52.686Z","status":"ssl_error","status_checked_at":"2026-05-16T04:41:52.009Z","response_time":115,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","agentic-ai","agents","ai","ai-coding","byok","cli","code-generation","code-review","coding-agent","developer-tools","local-first","open-source","ratatui","repo-context","rust","semantic-search","terminal","tui","verification"],"created_at":"2026-05-02T04:01:34.655Z","updated_at":"2026-05-20T06:12:33.178Z","avatar_url":"https://github.com/phonton-dev.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/readme/phonton-cli-logo.png\" width=\"112\" alt=\"Phonton CLI logo\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003ePhonton CLI · v0.16.1\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eVerified code changes with repo memory.\u003c/strong\u003e\u003cbr\u003e\n  A local-first agentic development environment for developers who want autonomous code changes without giving up review control.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/phonton-dev/phonton-cli/actions/workflows/ci.yml\"\u003e\u003cimg alt=\"CI\" src=\"https://github.com/phonton-dev/phonton-cli/actions/workflows/ci.yml/badge.svg\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/phonton-dev/phonton-cli/stargazers\"\u003e\u003cimg alt=\"GitHub stars\" src=\"https://img.shields.io/github/stars/phonton-dev/phonton-cli?style=flat\u0026label=stars\"\u003e\u003c/a\u003e\n  \u003cimg alt=\"release\" src=\"https://img.shields.io/badge/release-v0.16.1-6c63ff\"\u003e\n  \u003cimg alt=\"license\" src=\"https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue\"\u003e\n  \u003cimg alt=\"status\" src=\"https://img.shields.io/badge/status-public_alpha-f97316\"\u003e\n\u003c/p\u003e\n\n---\n\nPhonton plans the work, routes it through local repo context, verifies changes before handoff, and keeps the result reviewable. The goal is not to be the loudest coding agent. The goal is to make AI-assisted development feel less reckless.\n\n\u003e Current status: pre-1.0 public-alpha quality. The core loop is real, the CLI runs, and the Rust workspace is tested. Public launch claims should stay tied to reproducible benchmarks.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/readme/phonton-cli-hero.png\" alt=\"Phonton CLI hero with terminal UI preview\"\u003e\n\u003c/p\u003e\n\n## Why Phonton\n\nMost coding agents start with chat. Phonton starts with the engineering loop:\n\n```mermaid\nflowchart LR\n    A[\"Goal\"] --\u003e B[\"Plan preview\"]\n    B --\u003e C[\"Repo-aware worker\"]\n    C --\u003e D[\"Verification gate\"]\n    D --\u003e E[\"Reviewable diff\"]\n    E --\u003e F[\"Memory and history\"]\n    F --\u003e B\n```\n\nThat gives Phonton a different shape from an IDE assistant or a chat-first terminal assistant:\n\n- **Review first:** plans and diffs are first-class surfaces, not buried in a conversation.\n- **Verification first:** generated work is expected to pass checks before it is treated as ready.\n- **Local first:** config, trust, store, memory, and repo context live on your machine.\n- **BYOK:** use your own provider account instead of routing every task through a Phonton-hosted model bill.\n- **Measured claims:** token and cost efficiency should be benchmarked per task, not guessed.\n\n## Trust Demo Loop\n\nThe product promise is intentionally narrow:\n\n```text\ngoal -\u003e plan -\u003e edit -\u003e verify -\u003e review -\u003e remember\n```\n\nTry the proof-oriented demo text before configuring a provider:\n\n```bash\nphonton demo trust-loop\nphonton demo trust-loop --json\n```\n\nIt walks through the evidence trail a real run should expose: GoalContract, plan preview, verification failure and retry, review receipt, known gaps, rollback point, and memory prompt.\n\n## What Works Today\n\n- Interactive Ratatui TUI with goal, task, ask, settings, git, and flight-log surfaces.\n- v0.16.1 adds `phonton extensions install \u003csource\u003e` for installing audited `.phonton` packs from GitHub or local paths, plus built-in open-source MCP catalog ids such as `context7`, `github`, `chrome-devtools`, `playwright`, `firecrawl`, `supabase`, `mongodb`, and `figma`.\n- v0.16.1 adds `phonton extensions catalog`, `phonton extensions new \u003cpath\u003e [skill|steering|mcp-server|profile]`, and `phonton extensions validate` so extension discovery, scaffolding, and validation feel closer to Gemini CLI while preserving Phonton's local trust and approval model.\n- v0.16.0 adds typed `@...` context mentions for files, directories, symbols, MCP servers, and MCP tools, with resolved/missing/approval-gated rows visible in `/context` and the Context focus surface.\n- v0.16.0 separates local prompt token estimates from provider-reported billing usage in `phonton why-tokens --by-source`; local-only runs now render as `no provider call`, and prompt manifests carry resolved `@...` mention rows plus attribution-only token totals instead of double-counting attachments or MCP/tool context.\n- v0.16.0 tightens extension and MCP diagnostics so `phonton extensions doctor` warns on networked or mutating MCP trust even when a server has not listed explicit permissions.\n- Unified slash commands in the TUI: `/settings`, `/config`, `/status`, `/context`, `/compact`, `/compact-context`, `/compress`, `/problems`, `/diagnostics`, `/retry`, `/repair`, `/why-tokens`, `/ask`, `/plan`, `/approve`, `/goals`, `/switch`, `/focus`, `/diff`, `/code`, `/copy`, `/rerun`, `/stats`, `/stop`, `/review`, `/memory`, `/permissions`, `/trust`, `/model`, `/commands`, `/run`, and `!` all route through the same command registry and prompt drawer.\n- Static syntax verification now covers Rust, Python, JavaScript, TypeScript, JSON, TOML, YAML, HTML, and CSS changed files before review-ready status. Generated code that cannot parse stays failed/unverified instead of becoming a receipt.\n- Failed goals default to a Problems focus view with grouped verifier/provider/quality diagnostics, compact repair hints, and `Alt+P` / `Alt+R` keyboard shortcuts for inspection and repair.\n- `/why-tokens` and `phonton why-tokens --by-source` explain the latest prompt manifest in plain language, including first-attempt, repair-attempt, context/artifact, system, goal, memory, attachment, repo-code, MCP/tool, `@...` mention attribution, retry, compaction, dedupe, and cached-token buckets.\n- v0.15.5 fixes TUI prompt typing and Ask readability: bare `f`, `d`, `p`, and `r` now type normally, focus shortcuts moved to `Alt+F/D/P/R`, the prompt bar shows a static caret rectangle, and Ask answers style inline markdown such as `**bold**`, `*italic*`, and `` `code` ``.\n- v0.15.4 fixes the existing Vite chess quality gate: the zero-token App shell now renders an accessible named-piece legend for king, queen, rook, bishop, knight, and pawn, and the seeded App test asserts that evidence.\n- v0.15.3 fixes stale existing Vite App tests during the zero-token chess UI seed: old placeholder heading assertions in `src/App.test.*` are replaced with a local Vitest server-render test for the generated chess shell.\n- v0.15.2 fixes the existing Vite chess UI hot path: `src/App.tsx`, `src/App.css`, and `src/vite-env.d.ts` seed locally with a playable app shell, repeated UI slices become zero-token no-ops, and the TUI no longer shows a blinking native cursor over the prompt or compact header.\n- v0.15.1 fixes the v0.15.0 hot path: generated Vite chess rules seeds declare a real Vitest suite, the compact header gradient animates while work is active, the Receipt focus shortcut row no longer wraps `d diff` onto a stranded line, and Flight Log PgUp/mouse scrolling works from tail mode.\n- v0.15.0 adds a summary-first proof layer: deterministic Plan, Work, Verification, Failure, Token, Context, and Handoff summaries are derived from typed facts and exported through proof/review surfaces.\n- v0.15.0 expands the Active panel focus surfaces to Plan, Receipt, Problems, Code, Commands, Context, Tokens, and Log so broad work can be inspected without opening the Flight Log.\n- `/plan \u003cgoal\u003e` now previews the GoalContract and verification/run plan in the TUI without starting workers; `/approve` starts the selected preview after review.\n- OutcomeLedger proof records now carry persisted context buckets, selected index slices, MCP permission evidence, command-run evidence, and summary bundles for history, review JSON, proof export, and benchmark export.\n- Generated web/runtime verification plans that do not produce runtime proof are surfaced as known gaps and verification findings, not treated as proof of correctness.\n- v0.11 context planning builds a compact repo map, selects only the highest-value code slices under a target budget, exposes omitted code tokens, and labels target-exceeded prompts honestly when one required slice must go over budget.\n- v0.12 enforces lower spend before the provider call: generated app/game goals dispatch as acceptance-slice subtasks, simple/docs/test prompts use small task-class budgets, generated repairs use a sub-1k context target, semantic retrieval top-k and repo maps shrink by task class, MCP result context is capped, and provider output ceilings are lower.\n- v0.14.1 fixes generated-web failure diagnostics: Problems focus now jumps to the changed file named by the verifier, and `src/App.tsx:1:1` diagnostics are normalized for retry policy.\n- v0.14.0 hardens Node verification so stock Vite/Vitest/Jest test scripts run in non-interactive CI mode instead of hanging in watch mode.\n- v0.13.5 seeds the existing Vite/React chess rules/test boundary with a locally verified template before provider UI slices, including recovery from partial invalid `src/chessRules.ts` artifacts without another provider call.\n- v0.13.4 detects existing Vite/React workspaces for chess benchmark prompts that say \"use the existing project stack,\" then starts on source/test slices instead of fragile `package.json` or `index.html` scaffold edits.\n- v0.13.1 hardens generated web-app token behavior: Vite/React chess prompts stay on compact acceptance slices even in partial workspaces, and first-attempt TSX/HTML syntax failures stop before automatic repair.\n- v0.13.0 makes Ask workspace-aware under a bounded context budget and carries forward verified diff export: `phonton diff`, `--stat`, `--name-only`, `/diff`, `/code`, and `d`.\n- v0.12.6 hardens provider contracts further: DeepSeek V4/reasoner routes disable provider thinking for diff-only worker calls, stale v0.12.5 canary cache entries are invalidated, reasoning-only replies fail clearly, and provider tests time out quickly instead of hanging.\n- v0.12.5 blocks bad provider/model routes before goal dispatch: provider readiness now uses a parseable unified-diff canary, empty OpenAI-compatible responses fail immediately, OpenCode/OpenCode Go routes work through `OPENCODE_API_KEY`, and `phonton providers` can list/sync the Models.dev catalog.\n- v0.12.4 cuts wasted repair tokens in generated-app failures: workers stop after repeated verifier/parser diagnostics, redispatch prompts start with prior verifier evidence, stale hunk repairs get explicit guidance, and the Flight Log shows compact `repair` events before bounded retries.\n- v0.12.3 fixes stale generated-test hunks during the chess benchmark: rules/test slices now carry paired current artifacts, and repair attempts include the exact current file named in verifier diagnostics instead of retrying blind.\n- v0.12.2 fixes early generated Vite/React chess slices so Vitest does not fail before test files exist: scaffold slices now request a starter rules module and smoke test, and npm verification waits to run Vitest/Jest discovery scripts until a test file exists.\n- v0.12.1 fixes the playable chess benchmark path: explicit Vite/TypeScript/React prompts now scaffold an npm app contract, use chess.js-backed rules/test slices, carry current artifact snapshots between slices, use compact slice labels instead of repeating the full pasted prompt, and run npm install/test/build verification before review-ready status.\n- `phonton proof export --latest --format json` exports the latest proof bundle from the OutcomeLedger, and `phonton context eval|diff` evaluates deterministic context-selection fixtures before benchmark runs.\n- Ask mode supports `/ask \u003cquestion\u003e`, scrollable answers, lightweight markdown-style rendering, and bounded read-only workspace context with visible `ctx:` token/file summaries. `phonton ask --no-workspace` keeps the old stateless behavior.\n- Faster multi-goal navigation: the sidebar shows stable goal indexes, `Alt+Up` / `Alt+Down` switches goals even while drafting text, `Alt+1` through `Alt+9` jumps directly, and `/goals` opens a searchable switcher.\n- Review-ready goals now default to a Receipt focus view, with Plan, Problems, Code, Commands, Context, Tokens, and Log tabs in the Active panel plus `p` / `r` / `f` / `d` / `[` / `]` keyboard navigation.\n- Command run receipts stay collapsed by default; the Commands focus view shows status, exit code, duration, and short stdout/stderr previews. `/rerun` repeats the latest command through the same sandbox path and `/copy` copies the current focus view to the Windows clipboard.\n- Saved workspace sessions: use `phonton -r` or `phonton --resume` to reopen the last saved TUI conversation for the current repo.\n- Prompt bar paste artifacts: long or multiline pasted text collapses into a compact colored chip while the full content stays attached to the submitted goal; credential-looking pasted blocks are blocked before they can reach the model.\n- Image path paste/drop artifacts: pasted image file paths collapse into `[image: name.png]` chips and flow into the submitted prompt as image artifacts.\n- Active review/code output is scrollable with the mouse wheel, `PgUp` / `PgDn`, and `Home` / `End`, so large generated diffs do not trap the user at the top of the receipt.\n- Windows clipboard import in the TUI with `Ctrl+V`, including content selected from Windows clipboard history (`Win+V`) when the terminal does not emit bracketed paste directly.\n- Lower-noise worker prompts: first attempts omit bulky diff examples, duplicate repo context slices are deduped, and Flight Log prompt manifests show repo-code, compaction, dedupe, and budget buckets.\n- Resumed sessions keep recent prompt history, and the History view supports in-place filtering and row selection for inspecting previous task receipts.\n- Workspace trust is saved as structured per-workspace records, mirrored into the local store, visible with `/trust current` or `/trust list`, and revocable with `/trust revoke-current`.\n- Sandboxed command runs from the prompt bar with `/run \u003ccmd\u003e` or `!\u003ccmd\u003e`, plus command status, output previews, context meters, and permission mode controls in the TUI and Flight Log.\n- `phonton doctor` setup diagnostics for config, provider key, store, trust, git, cargo, and Nexus config.\n- `phonton plan` preview for task DAGs and the visible GoalContract before edits happen.\n- `phonton review` surfaces for verified diff review payloads, approvals, rejections, rollback, and Markdown receipt export. `phonton diff` exports the verified unified diff or compact file/stat views without opening the TUI. Failed runs can still export a failed/unverified Markdown receipt with diagnostics.\n- `phonton run latest` executes the latest receipt-suggested run command through the sandbox.\n- TUI goal prompts can mention workspace files and images with `@path`; text files become bounded context and image metadata/payloads flow to compatible providers.\n- Review-ready runs now show a handoff receipt in the TUI and persist a minimal outcome ledger for history/review evidence.\n- `phonton memory` commands for inspecting, editing, deleting, pinning, and unpinning local decision memory.\n- `phonton extensions` commands for inspecting resolved skills, steering, MCP servers, profiles, conflicts, and diagnostics.\n- `phonton mcp` commands for listing configured servers and lazily approving tool discovery or tool calls.\n- BYOK provider adapters for Anthropic, OpenAI, OpenRouter, OpenCode, OpenCode Go, Gemini/Google, Cloudflare Workers AI, AgentRouter, DeepSeek, xAI/Grok, Groq, Together, Ollama, and custom OpenAI-compatible endpoints. `phonton doctor --provider` verifies your configured provider with a tiny parseable-diff canary through the same adapter used for runs.\n- `phonton providers list|sync|doctor|import-opencode` exposes Models.dev provider metadata, verifies the configured provider/model route, and can read OpenCode auth on demand without copying or printing secrets.\n- Local store, memory, planner, worker, diff, sandbox, verification, and orchestration crates.\n- Prompt-section token manifests in the Flight Log so system, goal, memory, attachment, MCP, and retry-context costs are inspectable.\n- `phonton demo trust-loop` prints a compact proof-oriented walkthrough of the GoalContract -\u003e verification -\u003e receipt -\u003e memory loop for first-run demos, with `--json` for reproducible demos.\n- Semantic indexing behind the CLI stack for repo-aware workflows.\n\n## What Is Still Early\n\nPhonton is not yet as polished as Codex, Claude Code, Cursor, or Windsurf. It has fewer integrations, less onboarding polish, narrower public documentation, and no mature hosted/team workflow yet.\n\nThe current release target is a public alpha for real Rust repo tasks. Phonton can ask configured models to write app-sized changes, but quality is only claimed after plan review, sandboxed edits, verification, and human review. Use it if you are comfortable running a Rust binary, reading diagnostics, and filing sharp bug reports.\n\n## Install\n\nThe easiest install path is npm. This downloads a prebuilt GitHub Release binary when the package installs.\n\n```bash\nnpm install -g phonton-cli\nphonton\n```\n\nRun without installing:\n\n```bash\nnpx phonton-cli\n```\n\nCargo still works if you prefer building from source. Rust is required for the Cargo path.\n\nmacOS/Linux:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/phonton-dev/phonton-cli/main/scripts/install.sh | sh\n```\n\nWindows PowerShell:\n\n```powershell\n\u0026 ([scriptblock]::Create((irm https://raw.githubusercontent.com/phonton-dev/phonton-cli/main/scripts/install.ps1)))\n```\n\nDirect Cargo install:\n\n```bash\ncargo install --git https://github.com/phonton-dev/phonton-cli --tag v0.16.1 phonton-cli --locked --force\n```\n\nCheck the install:\n\n```bash\nphonton version\nphonton doctor\n```\n\n## Release Channels\n\nPhonton uses GitHub branches and releases as install channels:\n\n| Channel | Install | Use when |\n|---|---|---|\n| Stable | `cargo install --git https://github.com/phonton-dev/phonton-cli --tag v0.16.1 phonton-cli --locked --force` | You want the best validated public alpha |\n| Dev | `cargo install --git https://github.com/phonton-dev/phonton-cli --branch dev phonton-cli --locked --force` | You want next-release integration changes |\n| Nightly | `cargo install --git https://github.com/phonton-dev/phonton-cli --branch nightly phonton-cli --locked --force` | You want daily snapshots and can tolerate breakage |\n| Main | `cargo install --git https://github.com/phonton-dev/phonton-cli --branch main phonton-cli --locked --force` | You want the current release branch tip |\n\nFor the channel policy and automation, read [docs/RELEASE_CHANNELS.md](docs/RELEASE_CHANNELS.md).\n\n## Build From Source\n\n```bash\ngit clone https://github.com/phonton-dev/phonton-cli.git\ncd phonton-cli\ncargo build --release -p phonton-cli\n```\n\nRun the binary:\n\n```bash\n./target/release/phonton\n```\n\nOn Windows:\n\n```powershell\n.\\target\\release\\phonton.exe\n```\n\n## Configure A Provider\n\nPhonton reads `~/.phonton/config.toml` and also checks provider-specific environment variables.\n\nMinimal config:\n\n```toml\n[provider]\nname = \"gemini\"\nmodel = \"gemma-4-31b-it\"\n\n[budget]\nmax_tokens = 120000\nmax_usd_cents = 200\n```\n\nEnvironment-variable setup examples:\n\n```bash\nexport ANTHROPIC_API_KEY=\"...\"\nexport OPENAI_API_KEY=\"...\"\nexport GEMINI_API_KEY=\"...\"\nexport OPENROUTER_API_KEY=\"...\"\nexport CLOUDFLARE_API_TOKEN=\"...\"\nexport CLOUDFLARE_ACCOUNT_ID=\"...\"\n```\n\nWindows PowerShell:\n\n```powershell\n$env:GEMINI_API_KEY = \"...\"\n$env:CLOUDFLARE_API_TOKEN = \"...\"\n$env:CLOUDFLARE_ACCOUNT_ID = \"...\"\n```\n\nCloudflare Workers AI uses the OpenAI-compatible endpoint. Set\n`name = \"cloudflare\"` and the default model is `@cf/moonshotai/kimi-k2.6`.\nSet `provider.account_id` or `CLOUDFLARE_ACCOUNT_ID` for the Workers AI account.\n`provider.base_url` remains available for a full\n`https://api.cloudflare.com/client/v4/accounts/\u003cid\u003e/ai/v1` base URL override.\n\nCheck the install:\n\n```bash\nphonton doctor\nphonton doctor --provider\n```\n\n`phonton doctor --provider` proves the configured key/model/base URL can make a real completion call. It does not claim every listed provider works for every account, model name, quota state, or proxy configuration.\n\n## CLI Commands\n\n```text\nphonton                 Launch the interactive TUI\nphonton -r              Resume the saved TUI session for this workspace\nphonton init            Create ~/.phonton/config.toml if it is missing\nphonton ask [flags] \u003cq\u003e Workspace-aware Q\u0026A using the configured provider\nphonton demo trust-loop Print the evidence-trail demo loop\nphonton doctor          Check config, store, trust, git, cargo, and Nexus\nphonton plan \u003cgoal\u003e     Preview the task DAG and GoalContract without changing files\nphonton review          Show verified diff review payloads\nphonton diff            Print verified unified diffs from review-ready tasks\nphonton run latest      Run the latest receipt-suggested command\nphonton memory list     Inspect local decision memory\nphonton extensions      Install and inspect skills, steering, MCP servers, and profiles\nphonton mcp list        Show configured MCP servers without starting them\nphonton config path     Print the resolved config file path\nphonton config show     Dump resolved config as TOML\nphonton version         Print version\n```\n\nInside the TUI prompt bar:\n\n```text\n/settings, /config      Open provider/model/budget settings\n/status                 Show version, provider, model, workspace, and token state\n/review                 Show review receipt guidance for the selected goal\n/ask \u003cquestion\u003e         Ask a bounded workspace question without queueing a goal\n/plan \u003cgoal\u003e            Preview a GoalContract and plan without execution\n/approve                Execute the selected plan preview\n/diff, /code, d         Jump to verified Code/Diff focus\n/memory                 Inspect local decision memory\n/permissions            Show sandbox, trust, and approval status\n/trust                  Show or revoke workspace trust records\n/model set \u003cname\u003e       Save a model preference\n/commands               Show slash-command and keyboard help\n/run \u003ccmd\u003e              Run a sandboxed command\n!\u003ccmd\u003e                  Shorthand for a sandboxed command\nCtrl+V                  Paste from the Windows clipboard\nCtrl+U / Ctrl+K         Clear before / after cursor\nPgUp / PgDn             Scroll the Active receipt/code surface\nMouse wheel             Scroll the visible Active, Ask, or Flight Log surface\nTab                     Complete slash commands\n```\n\nPlan preview:\n\n```bash\nphonton plan --json \"add input validation to config loading\"\n```\n\nThe text preview shows the visible GoalContract, including acceptance criteria,\nlikely files, verification plan, run plan, assumptions, and clarifications.\n\nReview latest completed task:\n\n```bash\nphonton review latest\nphonton review latest --markdown\nphonton review approve latest\nphonton review reject latest\n```\n\nRun the latest suggested command from a review receipt:\n\n```bash\nphonton run latest\nphonton run latest --index 2\n```\n\nMemory management:\n\n```bash\nphonton memory list --json\nphonton memory edit \u003cid\u003e \"updated rationale\"\nphonton memory pin \u003cid\u003e\nphonton memory delete \u003cid\u003e\n```\n\nExtension visibility:\n\n```bash\nphonton extensions catalog\nphonton extensions install context7\nphonton extensions install https://github.com/phonton-dev/phonton-review-gate-extension\nphonton extensions new ./my-extension skill\nphonton extensions list --json\nphonton extensions doctor --json\nphonton extensions validate --json\nphonton skills list --json\nphonton steering list --json\nphonton mcp list --json\n```\n\n## How Phonton Handles Context\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/readme/context-efficiency.png\" alt=\"Diagram contrasting whole repo context with compact context packs and verified diffs\"\u003e\n\u003c/p\u003e\n\nPhonton is built around a simple rule: do not blindly dump the whole repo into the model.\n\n```mermaid\nflowchart TD\n    Repo[\"Local repo\"] --\u003e Index[\"Source index\"]\n    Index --\u003e Planner[\"Planner\"]\n    Planner --\u003e Pack[\"Task-specific context\"]\n    Pack --\u003e Worker[\"Worker\"]\n    Worker --\u003e Verify[\"Verify\"]\n    Verify --\u003e Review[\"Review\"]\n    Review --\u003e Store[\"Memory and event store\"]\n    Store --\u003e Planner\n```\n\nThe intended result is lower context waste and better reviewability. The honest way to prove that is with benchmarks, so this repo includes a benchmark harness instead of hard-coded marketing numbers.\n\n## Benchmarks\n\nRun the plan benchmark harness:\n\n```powershell\n.\\scripts\\benchmark-plan.ps1\n```\n\nIt runs repeatable planning tasks, captures estimated Phonton tokens versus the planner's naive baseline, and writes Markdown plus JSON reports to `benchmarks/results/`.\n\nExport the latest real OutcomeLedger run:\n\n```powershell\nphonton benchmark export --latest --format json\nphonton proof export --latest --format json\nphonton context eval fixtures/context.json --format json\nphonton context diff --indexed --non-indexed fixtures/context.json --format json\nphonton why-tokens --by-source\n```\n\nBenchmark exports require provider-reported token usage. Estimated-token receipts remain useful for review, but they are not valid for public efficiency claims.\n\nRead the methodology in [docs/BENCHMARKS.md](docs/BENCHMARKS.md).\n\nImportant: benchmark output is evidence, not a slogan. Do not claim \"X percent savings\" publicly until you can reproduce it on multiple real tasks and include the raw report.\n\n## Architecture\n\n```mermaid\nflowchart TB\n    CLI[\"phonton-cli\"] --\u003e Planner[\"phonton-planner\"]\n    CLI --\u003e Orchestrator[\"phonton-orchestrator\"]\n    Orchestrator --\u003e Worker[\"phonton-worker\"]\n    Orchestrator --\u003e Verify[\"phonton-verify\"]\n    Worker --\u003e Providers[\"phonton-providers\"]\n    Worker --\u003e Context[\"phonton-context\"]\n    Context --\u003e Index[\"phonton-index\"]\n    Verify --\u003e Diff[\"phonton-diff\"]\n    Verify --\u003e Sandbox[\"phonton-sandbox\"]\n    Planner --\u003e Memory[\"phonton-memory\"]\n    Memory --\u003e Store[\"phonton-store\"]\n    Types[\"phonton-types\"] --\u003e CLI\n    Types --\u003e Orchestrator\n    Types --\u003e Worker\n```\n\nRepository layout:\n\n- `phonton-cli` - terminal UI and user-facing command surface.\n- `phonton-planner` - goal decomposition and plan preview.\n- `phonton-orchestrator` - task state, dependencies, retries, and event flow.\n- `phonton-worker` - model-call loop, tool policy, and patch generation.\n- `phonton-verify` - syntax/type/test/decision checks before review.\n- `phonton-index` - local source indexing and semantic retrieval.\n- `phonton-context` - task-specific context compilation.\n- `phonton-diff` - diff application and rollback support.\n- `phonton-memory` / `phonton-store` - local persistence and decision memory.\n- `phonton-providers` - BYOK provider adapters.\n- `phonton-sandbox` - command execution policy.\n- `phonton-types` - shared domain contracts.\n\n## Release Checks\n\nBefore cutting a release:\n\n```powershell\n.\\scripts\\release-check.ps1\n```\n\nThe script runs formatting, clippy, tests, release build, doctor, and the plan benchmark harness.\n\nManual checks worth doing before a public release:\n\n- Fresh clone install on Windows, macOS, and Linux.\n- `phonton doctor --provider` with at least one hosted provider, confirming both model discovery and a completion call.\n- One real repo task from goal to reviewable verified diff.\n- Benchmark report committed or attached to the release notes.\n- No secrets printed in logs, screenshots, or benchmark output.\n\n## Comparison\n\nPhonton is not trying to win by pretending the incumbents are weak.\n\n| Tool | Strongest fit | Where Phonton is trying to be different |\n|---|---|---|\n| Codex | Mature agent workflow, cloud/editor/CLI integration | Local-first ADE kernel, BYOK, explicit verification and review surfaces |\n| Claude Code | Excellent terminal-native coding agent | Less chat-first, more plan/verify/review oriented |\n| Cursor | Polished AI editor experience | Less editor polish, more auditable repo workflow |\n| Windsurf | Agentic IDE workflow | Narrower release scope, explicit local-first positioning |\n| Phonton CLI | Verified local ADE loop for serious repo tasks | Early product, smaller ecosystem, benchmark claims still being built |\n\n## Development\n\n```bash\ncargo fmt --all -- --check\ncargo clippy --locked --workspace --all-targets -- -D warnings\ncargo test --locked --workspace\ncargo build --locked --release -p phonton-cli\n```\n\nRun from source:\n\n```bash\ncargo run -p phonton-cli -- doctor\ncargo run -p phonton-cli -- plan \"add input validation to config loading\"\n```\n\n## License\n\nLicensed under either of:\n\n- Apache License, Version 2.0\n- MIT License\n\nat your option.\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/chart?repos=phonton-dev/phonton-cli\u0026type=date\u0026legend=top-left)](https://www.star-history.com/?repos=phonton-dev%2Fphonton-cli\u0026type=date\u0026legend=top-left)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphonton-dev%2Fphonton-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphonton-dev%2Fphonton-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphonton-dev%2Fphonton-cli/lists"}