Quick Start

npm install -g [email protected]
phonton doctor
phonton config edit   # add your provider API key
phonton goal "fix the failing npm test in this repo"

Headless benchmark-style runs:

phonton goal --prompt-file prompt.md --yes --json --permission-mode full-access
phonton review latest --json
phonton benchmark export --latest

When a run finishes, open the Receipt focus in the TUI (or phonton review latest) for changed files, verification evidence, run commands, known gaps, and rollback points. Use /why-tokens to see index, memory, and attachment contributions.

What Is Phonton?

Phonton CLI is a local-first agentic development environment (ADE), not a generic chatbot. It is built around the accountable development loop:

goal -> plan -> edit -> verify -> review -> remember

You bring your own model keys or local model runtime. Phonton runs locally, keeps its state in local files and SQLite, and sends selected task context only to the provider or local model you configure. There is no Phonton-hosted proxy between your workspace and your chosen provider.

Why Phonton?

Visible Goal Contracts

Before broad work starts, Phonton turns the request into a GoalContract with acceptance criteria, expected artifacts, likely files, verification commands, assumptions, and clarification questions.

Interactive Clarification Questionnaire

v0.19.6 integrates a fully Interactive Clarification Questionnaire inside the TUI. When requirements are under-specified (confidence < 70% or unanswered questions), execution suspends, guiding the user step-by-step directly in the terminal, automatically appending answers to the prompt, and initiating a clean planning rerun.

Diff-Only Workers

Workers produce code changes as diffs. Phonton does not treat worker prose as the primary artifact, and unverified changes are not promoted as review-ready.

Layered Verification

Phonton verifies changes with the checks that fit the workspace: patch applicability, syntax checks, memory/decision checks, Cargo checks and tests, Node test scripts, and browser rendering checks for web projects when applicable.

Typed Handoff Packets

After verification, Phonton writes a typed HandoffPacket with changed files, verification evidence, run commands, known gaps, rollback points, token/cost summary, and context influence. Review starts from evidence rather than a chat summary.

Local Memory And Code Retrieval

Phonton stores task history, decisions, rejected approaches, and conventions in local SQLite. Code context is retrieved through local symbol indexing and HNSW search by default, with an optional Qdrant backend for code retrieval in larger workspaces.

BYOK Providers And MCP Approval Gates

Phonton supports Anthropic, OpenAI, OpenRouter, Gemini, Ollama, AgentRouter, Cloudflare, DeepSeek, xAI/Grok, Groq, Together, and custom OpenAI-compatible endpoints. MCP servers and extension packs are inspectable local config, and networked or mutating tool use goes through approval-aware flows.

Quick Install

Install from npm:

npm install -g phonton-cli
phonton version
phonton doctor

Install this exact release from source:

cargo install --git https://github.com/phonton-dev/phonton-cli --tag v0.19.6 phonton-cli --locked --force

Alternative installers:

curl -fsSL https://raw.githubusercontent.com/phonton-dev/phonton-cli/main/scripts/install.sh | sh

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/phonton-dev/phonton-cli/main/scripts/install.ps1)))

v0.19.6 Highlights

• Beautiful, guided Interactive Clarification step questionnaire (Mode::Clarify) directly inside the Ratatui TUI.
• Automatic prompt self-refinement by appending answers to the original goal description.
• Programmatic plan-rerun queueing with strict state, flight log, and checkpoint cleanup to prevent state leaks.
• Full verification coverage via new automated TUI unit testing.

Recent v0.19.x work also includes typed swarm planning metadata, conflict-group scheduling, pluggable local/Qdrant code retrieval, MCP capability previews, browser verifier cleanup, TUI version display, and auto-update controls.

Commands

# Launch the interactive Ratatui TUI
phonton

# Run a goal non-interactively through plan/edit/verify/review
phonton goal "add input validation to config loading" --yes

# Run an exact prompt file, useful for benchmark and CI harnesses
phonton goal --prompt-file prompt.md --yes --permission-mode full-access --json

# Preview the task graph and GoalContract without editing files
phonton plan --json "refactor auth layer"

# Audit configuration, providers, store, trust, git, Cargo, and index backend
phonton doctor --provider

# Export evidence from the latest run
phonton benchmark export --latest --format json

# Inspect MCP capability proposals without invoking tools
phonton mcp capabilities <server-id> --json

Configuration

Configure providers and the code index in ~/.phonton/config.toml:

[provider]
name = "deepseek"
model = "deepseek-v4-flash"

[provider.keys]
deepseek = "sk-deepseek-api-key-here"
anthropic = "sk-ant-api-key-here"
openai = "sk-proj-openai-key-here"

[index]
backend = "local-hnsw"

Optional Qdrant code retrieval:

[index]
backend = "qdrant"
qdrant_url = "http://127.0.0.1:6333"
qdrant_collection = "phonton-code"

Benchmark Honesty

Phonton is designed for context efficiency and accountable verification, but public comparisons require reproducible evidence: pinned fixtures, exact prompts, tool versions, model/provider names, provider-reported token usage where available, raw logs, final diffs, verification logs, quality review, and handoff evidence.

Do not treat local-template runs, estimates, or incomplete artifact sets as token-efficiency wins.

Crate Architecture

• phonton-cli: TUI, headless goal runner, benchmark export, and CLI commands.
• phonton-types: shared GoalContract, HandoffPacket, PlanGraph, events, and provider types.
• phonton-planner: goal decomposition, contract generation, and plan graph metadata.
• phonton-orchestrator: task scheduling, confidence gate, retries, verification, and handoff assembly.
• phonton-worker: context assembly, provider calls, diff-only output, repair prompts, and MCP flow.
• phonton-index: local HNSW symbol/code retrieval plus optional Qdrant retrieval.
• phonton-verify: patch, syntax, decision, Cargo, Node, and browser verification.
• phonton-memory and phonton-store: local memory facade and SQLite persistence.
• phonton-sandbox: command and tool execution guardrails.
• phonton-extensions and phonton-mcp: local extension loading and MCP runtime.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)

At your option.