Achon CLI

The Achon CLI is a hardware-aware, local-first terminal client for Achon AI. It can run ordinary inference through Ollama on the user's computer, while authenticated cloud models, repository memory, web research, and specialist delegation remain connected to the main Achon service.

Install

npm install -g @achon-ai/cli
achon

On its first launch, achon automatically uses the OAuth 2.0 device authorization flow. It opens the branded Achon sign-in page in your browser, displays a short one-time code in the terminal, stores the resulting renewable sign-in securely, and then continues directly into the CLI. Later launches go straight to the prompt. achon login remains available for signing in again or switching accounts. The npm package contains no shared API key or client secret, and an Achon account must be explicitly authorized for CLI access.

The CLI includes a branded interactive terminal interface with live tool activity, command approvals, session resume, and colour-aware output. Press / at the prompt to open the command palette, type to filter it, use the arrow keys to select an option, and press Enter or Tab to apply it. The composer stays available while Achon is reasoning or using tools, so follow-up messages can be entered immediately and are processed in order after the active response. Its bordered terminal panel shows contextual controls, the current working or thinking phase, elapsed time, queue depth, active model, and permission mode; each response ends with its total completion time. Commands with choices use an interactive picker: use the arrow keys and Enter, or press the displayed number for immediate selection. A direct fallback installer is also available from Achon:

npm install -g https://achon.co/cli/achon-cli.tgz
achon

Commands

achon                   # interactive coding session
achon --thorough        # deeper investigation, implementation, verification, and review
achon --thinking        # start with deeper reasoning enabled
achon --model thinking  # equivalent explicit model selection
achon resume            # resume an earlier Achon session
achon exec "your task"  # non-interactive task
achon exec --thinking "your task"
achon exec --thorough "your task"
achon exec --allow-codex "your task"      # permit one evidence-gated Codex CLI escalation
achon exec --allow-deepseek "your task"   # permit one evidence-gated DeepSeek V4 Pro escalation
achon exec --thorough --allow-codex --allow-deepseek "your task" # permit automatic capacity fallback
achon ps                         # active jobs plus persistent task contracts
achon task list --all            # task history, phases, and verification
achon task show TASK             # exact contract, checks, artifacts, and release state
achon task steer TASK "message"  # steer at the next safe tool boundary
achon task logs TASK             # task events and managed-preview logs
achon task cancel TASK
achon release profiles           # approved reversible release profiles
achon release profile install ./profile.json  # owner/admin action
achon release status TASK PROFILE
achon release apply TASK PROFILE
achon release rollback TASK PROFILE
achon index             # incrementally index the current repository
achon search "query"    # search indexed project code and lessons
achon teach ./docs      # add approved project documentation
achon feedback --good "lesson"
achon feedback --wrong "correction"
achon eval ./project-evals.json  # measure and record retrieval quality
achon eval --history            # show earlier evaluation runs
achon route "your task"         # preview automatic model routing
achon whoami            # show the signed-in account
achon skills            # list installed coding skill packs
achon skills --for "build a profile feature"  # preview automatic skill selection
achon models            # list fast and thinking models
achon local inspect     # inspect CPU, RAM, GPU, and disk
achon local plan        # recommend one model profile for this computer
achon local install --yes              # install, then choose knowledge interactively
achon local install --yes --knowledge full
achon local install --yes --knowledge system,knowledge
achon local install --yes --knowledge none # skills + model only
achon local install --profile lite --yes
achon local install --profile standard --yes
achon local install --profile coder --yes
achon local install --profile deep --yes
achon local status
achon local start       # start only Achon's managed Ollama process
achon local stop        # stop only a process Achon owns
achon local enable      # prefer local inference
achon local disable     # use the authenticated Achon cloud
achon local remove --yes # remove Achon config; leave Ollama/models intact
achon knowledge packs             # list authorized knowledge packs
achon knowledge configure         # choose full, preset, or custom-path sync
achon knowledge configure --pack system --pack knowledge
achon knowledge configure --path "Knowledge/Engineering"
achon knowledge sync              # download and embed changed notes only
achon knowledge search "question" # search the offline local index
achon knowledge status
achon knowledge remove --yes      # remove the local knowledge copy/index
achon status            # test authentication and server access
achon logout            # delete the locally stored token

Read-only project orientation

Requests that ask Achon to read a project's documentation, understand the system, and explain what the project is use a bounded orientation pass. Achon locates the real project root, inventories its safe files, reads the headings from every safe documentation file, extracts the highest-priority current and source-of-truth documents, inspects manifests and service definitions, and then produces one evidence-based briefing. It does not build the vector index or re-read documents over many model turns for this task.

The briefing reports its coverage explicitly. This orientation path is not a line-by-line correctness or security audit; requests for those deeper audits remain separate long-running jobs. State read-only and ask Achon to explain the project when orientation is the intended outcome.

Achon stores device credentials in macOS Keychain or Linux Secret Service. On headless Linux systems without an available Secret Service, it falls back to an atomic credential file inside the private ~/.achon directory. The directory is restricted to mode 0700 and the credential to mode 0600. Access tokens are short lived and renewed using a refresh token; the model key issued to the CLI is also short lived and restricted to the private achon-local, achon-local-coder, and achon-local-deep model routes.

For non-interactive CI, set ACHON_API_KEY to a separately issued API key. Existing API keys remain compatible. An interactive user can also run achon login --token to store one in the available protected credential store.

The Achon runtime and sessions are isolated under ~/.achon; normal Codex configuration and sessions under ~/.codex are not modified. Local runtime configuration is stored in ~/.achon/local-runtime.json with private file permissions and contains no credential. The package is pure JavaScript and downloads a model only after an explicit achon local install --yes. When escalation is approved, Codex runs only in an isolated server worker.

Local runtime

achon local plan detects the operating system, architecture, CPU, memory, supported GPU, free disk, and Ollama installation. It recommends one bounded profile instead of downloading every model: 4B Lite, 9B Standard, 14B Coder, or the slower 30B-A3B Deep hybrid profile for 48+ GB hosts. Users may override the recommendation explicitly.

When local inference is enabled and healthy, chat requests go directly to 127.0.0.1 and receive the packaged Achon root skills. If the local runner fails, the CLI may use the cloud only when cloud fallback is enabled and the device has been authorized with achon login. Repository memory, public-web research, Codex, DeepSeek, and other hosted capabilities always require the main Achon account. Disabling local inference preserves its configuration and models; removing it leaves the user's Ollama installation and model data untouched.

Local tool rounds disable hidden model reasoning through Ollama's supported reasoning_effort: none control. This prevents a thinking model from spending its complete response budget without returning an answer or tool call. A task marked local-required retries locally with a compact recovery envelope and never silently changes to cloud inference.

Selective local knowledge

Local Achon can maintain an offline copy of authorized Obsidian knowledge. During installation, users can choose skills only, the full authorized vault, named packs such as System or Knowledge, or one or more super-admin-approved vault paths. The server returns only selections authorized for the signed-in account; full-vault and custom-path downloads require super-admin access.

Synchronization uses a cryptographic manifest. Achon checks it automatically every six hours by default and downloads, stores, and re-embeds only files whose content hash changed. Removed or deselected notes are removed from the local copy. achon knowledge sync performs the same incremental check immediately; an unchanged check transfers no note content and performs no document embeddings. Existing local knowledge remains usable while offline.

Notes and their compact vector index are stored under ~/.achon/knowledge with private directory and file permissions. The local index uses the multilingual qwen3-embedding:0.6b Ollama model. Relevant excerpts are added to local-model prompts as untrusted, path-cited evidence. Notes marked local_sync: deny are never offered for download. achon knowledge remove --yes removes the local copy and index but does not change the server vault.

Coding skills

Achon automatically selects compact procedural skill packs for each request. Version 0.12 includes safe public-web research, repository comprehension, architecture and data contracts, debugging and verification, secure engineering, performance and reliability, TypeScript/React/Next.js, Python backends, SwiftUI/iOS, Android/Kotlin, product requirements, design systems/accessibility, design-to-code validation, plus the existing web, mobile, and product UI packs. Only the most relevant skills are injected so the local model's 8K context remains available for evidence and tool results.

When a task needs current information, Achon can search the public web and read selected HTTPS text pages through its authenticated server. Search snippets are treated only as leads; the agent opens relevant sources, prefers official or primary technical documentation, and cites final source URLs. The server blocks private and local addresses, embedded credentials, custom ports, unsafe redirects, oversized responses, and binary downloads. Raw external curl and wget research is blocked even in Full Access mode; localhost development checks are unaffected.

Server-side Codex escalation

Achon remains local-first. Normal tasks are completed by the private Qwen model; Codex is available only as an exceptional specialist for a task that is too large, cross-cutting, or capability-heavy for the local model. The gate requires repository inspection plus a complete handoff containing the user's request, Achon's intended outcome, evidence and attempts, the material blocker, active skill context, and the exact expected result. A user can explicitly request Codex, but repository evidence is still required.

Every delegation starts a fresh server job pinned to gpt-5.6-sol with high reasoning. Eligible non-secret source files are encrypted in transit, rebuilt as an isolated Git snapshot, and removed after the retention window. Codex cannot access the user's machine, other jobs, deployment systems, or the server's ChatGPT sign-in cache; model-generated commands have network disabled. The worker returns a patch that must pass git apply --check and receive separate approval before changing the local workspace. Interactive users approve both the handoff and patch. Headless Codex uses a server-side ChatGPT subscription login, not OpenAI API billing. Before each coding job, the server reads Codex's authenticated subscription rate limits. Codex is used while every applicable window has at least 10% remaining. Below 10%, Achon sends a focused secret-filtered snapshot of at most 250 files and 2 MB to DeepSeek V4 Pro, validates its unified patch, and keeps routing eligible coding and non-coding specialist work to DeepSeek until the reported Codex reset time. It then rechecks automatically. Only one external specialist can be used per turn. High-risk, security, architectural, and cross-cutting work may escalate automatically as soon as the agent has collected a workspace map plus a focused live read. Lower-risk explicit handoffs ask in interactive sessions or require --allow-codex and/or --allow-deepseek in headless mode. Automatic specialist-patch application additionally requires Full Access (or --full-auto) and still passes through task isolation and verification.

Feature-building requests automatically receive a compact UX baseline whenever they include a user-facing surface, even when the prompt does not say “UX” or “UI”. Achon considers the user goal, existing product patterns, primary flow, loading/empty/error/success states, responsive behavior, accessibility, and testable acceptance criteria without turning backend-only work into a redesign.

Model modes

Fast mode is the default for normal coding work. Coder routes to the 14B coding tier, while Thinking routes difficult architecture, debugging, and multi-step planning to the 30B-A3B deep tier on the Achon server. When device-local inference is enabled, these modes remain workflow intent and use the single hardware-sized model chosen during achon local install. A session automatically routes ordinary requests to fast mode and complex or risky work to thinking mode. Interactive sessions can pin /model thinking or /model fast, then restore routing with /model auto.

Running /model opens a numbered model picker and /mode opens the workflow picker. The composer footer always shows the model currently serving the session, including the model selected by automatic routing.

Private Experimental mode

Experimental is a server-entitled experience rather than an Ollama model. It is hidden from the model picker and rejected by the server unless the signed-in Achon identity appears in the explicit Experimental allowlist. The initial production entitlement is Newton only; super-admin status by itself does not grant access. Ross or another user must first be explicitly entitled and must then run achon experimental login for their own Achon account. Experimental assigns each Achon identity a separate private CODEX_HOME, even when users share a host OS account. Newton's Codex credentials and subscription are never shared.

On remote or headless Linux hosts, achon experimental login automatically uses Codex device-code authentication so the OAuth callback does not target an unreachable localhost browser listener. Desktop hosts retain the normal browser callback flow. Set ACHON_EXPERIMENTAL_LOGIN_METHOD=device|browser only when an administrator needs to override automatic detection.

Run achon experimental or choose Experimental from /model. Achon verifies the entitlement, requires a healthy local runtime, checks that the local Codex CLI is signed in through ChatGPT rather than an API key, and launches Codex with gpt-5.6-sol and high reasoning. A temporary per-process MCP configuration gives Codex two private tools: bounded read-only Achon Local analysis and a durable handoff writer. It does not modify the user's global Codex configuration. Codex remains responsible for edits and verification; local model output is treated as a draft and cannot recursively delegate back to Codex. Inherited OPENAI_API_KEY values are removed from the Experimental Codex process so it cannot silently switch to API billing. The protected Achon-source policy is checked before launch. An explicitly entitled super-admin such as Newton receives source-maintainer access in the protected Achon workspace and implements fixes directly. Issues and fixes.md must exist at the source root, must be read before editing, and must record the cause, approach, changed files, verification, release details, and residual risks for every change. Installed packages and production runtime state remain outside ad-hoc writes, and any deployment still uses an authenticated reversible release profile. A future entitled non-super-admin receives a read-only Codex sandbox in Achon's own source while retaining normal access in their other authorized projects.

For each local subtask, Codex can request fast, coder, or deep intent. Achon selects the matching installed local model when that rig has one (the dedicated server can therefore move between its 9B, 14B coder, and 30B deep models); a smaller local installation safely falls back to its configured hardware-sized model. The override is accepted only when Ollama reports the model as installed, and Experimental never substitutes cloud inference for this local tool. The write-capable supervised executor defaults to the measured 9B fast profile for reliable tool selection; coder and deep remain explicit choices.

A supervised write is complete only when the child emits a durable task ID, the inner record reaches complete, at least one required verification passes, and an independent before/after snapshot observes a change in the approved scope. Zero-exit processes, printed-but-unexecuted tool JSON, empty diffs, failed verification, missing task records, and truncated snapshots all fail closed and require fresh user approval before Codex takeover.

Codex records an identity-isolated continuation packet under ~/.achon/experimental/. When Codex reports subscription exhaustion and saves that state—or exits with an error—the launcher resumes an Achon Local session from the packet. The user can also run achon experimental --continue-local. Starting Experimental again later feeds the latest local handoff back to Codex. This preserves continuity, but it does not pretend the local model has access to unsaved Codex reasoning or make Codex subscription capacity unlimited.

Permissions

/permissions opens a numbered picker for Read Only, Workspace Access, and Full Access. Read Only blocks file edits and shell, and stays inside the project root. Workspace Access allows reads and edits inside the current workspace and asks before shell commands or file tools that use absolute/host paths outside that workspace. Full Access allows file tools anywhere on the host and runs shell without individual prompts; blocked secret paths, destructive-command restrictions, task isolation, and release rules remain active. Production changes can run autonomously only when deployment was explicit in the original request, the complete verification matrix passed, and an owner-approved reversible release profile exists. Irreversible migrations, destructive data changes, billing, and secret rotation always require Newton. The chosen permission is stored privately in ~/.achon/settings.json and becomes the default for future sessions. While Full Access is active, the composer continuously displays FULL ACCESS GRANTED in red.

For protected Achon source workspaces, write-capable actions are blocked for non-super-admin accounts regardless of permission level. /status shows the workspace policy and project id so a super-admin can add that ID to protected_project_ids in assistant/config/config.yaml.

Thorough workflow and project memory

achon --thorough uses the thinking model and a slower evidence-led workflow. Interactive start and resume never pre-index the workspace. Achon indexes only after the actual project root is known and repository evidence is needed, or when the user explicitly runs achon index. Broad roots such as /, /home, and a user's home directory are refused. Eligible project-source and documentation chunks are sent over HTTPS to the private Achon server, where they are isolated to the signed-in account and project. Achon, Codex, Grok, credential, build-output, binary, and oversized paths are excluded. This project-memory index is separate from the optional device-local Obsidian knowledge described above.

Thorough mode maps the repository, retrieves relevant code and approved lessons, prevents edits until it has inspected concrete evidence, compacts old session context, validates changes when possible, and performs an independent final review pass. achon teach and achon feedback store only explicitly approved references or corrections; they do not alter the base model weights.

Repository indexing runs as resumable background jobs. Code chunks include symbols, imports, references, routes, test associations, and file roles. Dense and exact sparse search produce a candidate set that is reranked with these code-specific signals before evidence is added to the model context.

Durable background tasks

Large audits and cross-project reviews automatically move to a detached worker so they survive terminal, SSH, or host-session interruptions. The open chat follows that worker with a spinner, the latest phase, and elapsed time. Press Esc on an empty composer to detach only the live view; the worker keeps running. Type a message and press Esc to persistently steer the active task at its next safe tool boundary. A completed result returns to an open conversation so the next follow-up retains its context. Long-running cloud tasks renew the device access and inference keys before expiry and retry one authentication failure without discarding the saved session.

Use /ps (or achon ps) for active jobs, persistent task phases, elapsed time, and verification progress; /task TASK shows the exact contract and checks; /logs TASK shows lifecycle and preview logs; /resume JOB attaches from chat; and achon attach JOB attaches from a shell. Explicit cancellation remains separate: /cancel TASK or achon task cancel TASK.

Verification and design tools

Every request receives a durable task contract with kind, risk, acceptance criteria, release intent, current phase, artifacts, and an exact verification matrix. Write-capable coding work runs in an isolated Git worktree or safe snapshot. Achon applies the resulting patch to the original workspace only after the required checks pass and git apply --check confirms it will not overwrite unrelated user changes.

The coding agent has dedicated tools for Git diff inspection, project check detection, focused tests, linting, type checks, builds, managed localhost previews, Playwright screenshots, axe accessibility checks, ImageMagick comparison, and JSON OpenAPI reference validation. UI work additionally uses a structured design contract, captures 398x850 mobile and 1440x900 desktop views, and requires an independent cloud visual critique score of at least 85 with no critical/high findings before production release. When no owner-scoped OpenAI or Anthropic design credential is available, Achon may return a local draft but records it as ineligible for production release.

Release profiles are administrator-installed, integrity-checked JSON contracts under ~/.achon/release-profiles. They bind one project to bounded preflight, build, deploy, health, log, and rollback commands. release_apply records the pre-release Git checkpoint, monitors the deployed service, and automatically runs the approved rollback command when deployment or health checks fail. The general shell tool cannot be used as a production-deployment bypass.

Evaluation suites

Coding quality landmarks (offline, no API):

node chat/cli/package-src/assets/evals/check-coding-quality-landmarks.mjs

Retrieval suite against project memory (after achon index in a git workspace):

achon eval chat/cli/package-src/assets/evals/achon-coding-quality.json

Autonomy orchestration fixtures (offline, no model/API calls):

npm --prefix chat/cli/package-src run eval:autonomy

An evaluation suite is a JSON file containing retrieval questions plus expected paths and terms. achon eval SUITE.json runs every case against the private project index and records only case IDs, pass/fail results, timing, and retrieved paths. Prompts and source contents are not stored in evaluation history. Approved engineering lessons remain a separate explicit action.