algo-cli-runtime 0.14.0

Agent runtime for tools, durable context, and verified work

Algo CLI

Website · Documentation · Security

An agent runtime for tools, durable context, and verified work. Algo CLI combines direct tool use, routed agent pipelines, persistent memory, repository intelligence, and a searchable cross-agent harness. Run locally with Ollama or connect Ollama Cloud, xAI Grok, and ChatGPT/Codex.

• Act: inspect files, edit code, run commands, and work with connected services.
• Remember: carry identity, lessons, memories, and reusable skills across sessions.
• Route: use direct chat for ordinary work or Agent Blocks for larger tasks.
• Verify: ground claims in tool results, Git evidence, and explicit safety policies.

Install the release candidate

Algo CLI requires Python 3.10 or newer. Version 0.14.0 is currently a release candidate and is not yet published on PyPI. Install a reviewed source checkout as an isolated command-line application:

git clone https://github.com/Seabass-up/algo-cli.git
cd algo-cli
pipx install .
# or: uv tool install .

After the package release is published, pipx install algo-cli-runtime and uv tool install algo-cli-runtime become the recommended stable-channel commands.

Optional extras are available for PDF rendering (algo-cli-runtime[pdf]) and experimental vector quantization (algo-cli-runtime[quantization]). The distribution installs the algo-cli command. Run algo-cli doctor for a side-effect-free readiness report.

Quick Start

# Local Ollama
ollama pull qwen3
algo-cli

# Ollama cloud model through local Ollama login
ollama signin
ollama pull qwen3:235b-cloud
algo-cli --model qwen3:235b-cloud

# Direct Ollama Cloud API and web tools
export OLLAMA_API_KEY="..."
algo-cli --cloud --model qwen3

# ChatGPT/Codex subscription (authenticate once with /chatgpt-login)
algo-cli --model gpt-5.5

# One-shot non-interactive JSON event mode (for bridges, scripts, CI)
algo-cli --oneshot --json "summarize this folder"
echo "what changed in main.py?" | algo-cli --oneshot --json
algo-cli --oneshot --json --approval-mode auto --cwd /path/to/project "fix the failing test"

Signed-in local Ollama can run :cloud models without OLLAMA_API_KEY. OLLAMA_API_KEY is only required for the direct Cloud API route (--cloud / /cloud on when an API key is present) and web tools. Embedding indexes currently use local Ollama models only; a configured cloud embedding backend falls back to local until Ollama Cloud exposes embedding models.

--oneshot --json emits one JSON object per line to stdout (NDJSON), suitable for subprocess consumption. --approval-mode never (default) denies approval-required tools and emits a tool_denied event; pass --approval-mode auto to grant them. Skill crystallization is disabled in one-shot mode. Event types: session_start, thinking, content, tool_call, tool_result, tool_denied, error, done. The bridge can rely on session_start first and done last as framing.

Runtime environment values can be stored in ~/.algo_cli/env — the CLI loads them automatically. Point to a different file with ALGO_CLI_ENV_FILE. Legacy ~/.ollama_cli locations are supported as migration aliases.

Optional xAI OAuth setup

xAI subscription OAuth is optional and is not configured out of the box. Algo CLI does not bundle or reuse a third-party OAuth client identity. To enable the provider, supply an OAuth client ID that you are authorized to use and configure it for the loopback redirect http://127.0.0.1:56121/callback:

export XAI_CLIENT_ID=your-authorized-client-id
algo-cli
# then run /xai-login

For persistent configuration, place XAI_CLIENT_ID=your-authorized-client-id in ~/.algo_cli/env, or use ALGO_CLI_ENV_FILE when you keep runtime settings elsewhere. /xai-status and /doctor report the provider as optional and unconfigured until XAI_CLIENT_ID is present. The client ID value is sent only in the standard OAuth authorization, code-exchange, and refresh requests; status output reports only whether it is configured. Algo CLI never falls back to the removed third-party identity or to XAI_API_KEY.

Privacy-safe context defaults

Every normal chat request sends the active conversation and the assembled Algo CLI system context to the selected inference provider. That context includes SOUL.md, IDENTITY.md, USER.md, saved memories, and relevant retrieved lessons when available. With a cloud model, this content may leave the machine. Automatic memory capture is on by default; /memory-auto off stops new automatic captures (it does not delete existing memories).

The installed harness corpus contains only public Algo CLI docs, skills, and runtime metadata. Other local agent stores, working-directory code retrieval, index-compute-lab, and skill run-history capture are off by default because retrieved or summarized content can become part of a model request.

• /harness external on opts in to supported Codex, Claude, OpenClaw, Mercury, and shared agent stores.
• /icl on opts in to ~/index-compute-lab; override its root with ALGO_CLI_INDEX_COMPUTE_LAB_ROOT.
• /code-rag on opts in to indexing source files beneath the active cwd and adding relevant snippets to model requests. /code-rag off disables retrieval and purges persisted code indexes.
• /skills on opts in to bounded run-summary capture under ~/.algo_cli/private/run_history.jsonl and automatic skill-candidate crystallization by a genuinely local, non-embedding Ollama model. There is no cloud fallback.
• /harness external off and /icl off rebuild the generated index without those records.

Common credential forms are redacted and connector/MCP JSON is metadata-only, but redaction is not a substitute for reviewing the sources you enable. See Privacy and local context.

Commands

Command	Description
/help	Show help
/model NAME	Switch model
/models	List local models
/host URL	Set local Ollama host
/cloud [on|off|status]	Set/toggle direct Ollama Cloud API mode; local Ollama login can run :cloud models with /cloud off
/xai-login / /xai-status	Manage optional xAI Grok OAuth; requires your XAI_CLIENT_ID, and API-key fallback is disabled
/chatgpt-login / /chatgpt-status	Manage ChatGPT/Codex OAuth; --device-code uses Codex CLI token import
/x-account status	Check separate X account OAuth status through xurl
/x-account draft-post / draft-reply	Create browser drafts for X posts/replies without publishing
/auto [on|off|status]	Set/toggle auto-approve for tool calls
/safe [on|off|status]	Set/toggle safe mode for shell/file tools
/policy [on|off|status]	Toggle Agent Block tool-policy enforcement (off by default)
/thinking [on|off|status]	Set/toggle thinking display
/memory-auto [on|off|status]	Inspect or toggle bounded, privacy-gated automatic memory capture after successful turns
/code-rag [on|off|status]	Opt in or out of cwd source indexing and prompt retrieval; off purges persisted indexes
/skills [on|off|status|crystallize]	Opt in to local run-history capture and review local-only skill candidates
/remember FACT	Save a long-term memory
`/intuition [on	off
/icl [on|off|status|ask|path]	index-compute-lab knowledge graph (auto-injected each turn when on)
/harness external [on|off|status]	Opt in or out of indexing other local agent stores
/route TASK	Preview task classification, pipeline, advisory budget, and tool policy
/agent init	Write a starter ~/.algo_cli/blocks.toml without overwriting an existing file
/agent [--pipeline NAME] TASK	Run a named Agent Blocks pipeline and record a resumable thread
/agent team [--roles A,B[,C,D]] TASK	Run 2–4 independent read-only specialists, then one integrating pipeline
/agent threads / /agent show ID	List persistent parent/child runs or inspect their evidence
/agent resume ID [TASK] / /agent fork ID TASK	Continue a thread or branch from its bounded handoff context
/kernel list / /kernel show NAME	Inspect kernel contracts without executing workloads
/kernel check [NAME]	Validate kernel imports, slash routes, metadata, and active action contracts
/status	Show current model, context usage, and active features
/verify [on|off|status]	Set/toggle claim-grounding verification
/reason status|guide|react|reflexion|tot|got|mcts|qcr|neuro_symbolic	Inspect or set reasoning posture
/memories	List memories
/forget ID	Delete a memory
/clear	Clear current conversation
/context [status|rebuild|clear]	Inspect or manage context compression
/save NAME / /load NAME	Save/load conversation
/cd PATH	Change tool working directory
/ctx NUM	Set context window (256–2,000,000)
/temp NUM	Set temperature (0.0–2.0, finite values only)
/toolmax NUM	Set max tool iterations (1–128)
/thinkevery NUM	Set tool-call reflection interval (1–128)
/pdf [--pages N] [--chars N] PATH	Extract local PDF text
/theme NAME	Switch visual theme
/info	Show configuration
/actions [TOPIC]	Show commands, tools, and harness stats
/selfcheck	Show improvement-relevant skills and harness stats
/reload	Reload config, tools, and harness index
/exit	Exit

Typing / in the prompt shows inline slash-command completions.

For the assistant/model, slash commands are session controls, not prose. The model is prompted to use session_slash for deterministic /read, /ls, /cd, and /cwd; session_command for non-file session controls such as /status, /mode, /context, /code-rag status, /harness refresh, /route, and /agent; and normal model-callable tools for actual work (write_file for edits, run_shell for tests/builds). Read-only/status session_command calls run without approval; state-changing commands, including /code-rag on and /code-rag off, and agent execution require approval. Runtime-triggered /agent calls are allowed from the parent chat loop, but recursive delegation from inside an Agent Blocks run is rejected. Toggle commands accept explicit idempotent forms such as /auto on, /safe off, /code-rag status, /thinking status, /verify on, and /cloud off.

/reason is called out in the model prompt as a reasoning-posture control. Use /reason status or /reason guide before changing it. Keep react for ordinary tool loops and simple edits; use reflexion after failed/partial attempts; tot, got, or mcts for ambiguous multi-path planning/search; qcr for comparing candidate solutions; and neuro_symbolic for verification-heavy logic, code invariants, contracts, math, or claim checking. Changing /reason does not replace evidence gathering or tool verification.

/route also shows an advisory Agent Blocks budget (block count, per-block iterations, and parallel-work signal). It never starts or truncates a pipeline automatically. Agent Block panels show tool-policy decisions. By default policies are previews only; use /policy on to restrict Agent Block tools to the displayed policy. Existing safe-mode and approval behavior remains authoritative.

Use /agent init to create a starter blocks.toml defining default, code-change, research, and review pipelines. Configured blocks use tool groups (read, web, write, shell) rather than raw tool names; set requires_change = true on blocks that must produce a verified file change. Invalid configuration falls back to the built-in pipeline with an error message.

/agent team follows the Algo delegation loop: classify the task, choose two to four explicit specialist roles, fan them out with fresh read-only contexts, join their evidence in deterministic role order, and hand that bounded context to one normal integration pipeline. Child threads never mutate the shared workspace. The integration pipeline is the sole write owner and retains the existing approval, safe-mode, required-change, Git-evidence, review, and recovery gates. This gives parallel exploration without parallel-edit conflicts or unbounded recursive swarms.

Agent runs are recorded in ~/.algo_cli/agent_threads.json (up to 100 recent records, with bounded outputs and turn history). /agent resume continues the same record with its prior evidence; /agent fork creates a child record for a distinct follow-up. Custom roles must be unique short names, and team size is structurally capped at four.

When a block reaches its iteration budget after gathering evidence, the CLI requests a tool-free partial summary and allows the finalizer to report those incomplete findings instead of discarding the run.

Partial and failed Agent Block panels include an explicit state reason, and partial reasons are passed to downstream blocks separately from the model's output text.

When a requires_change implementation becomes partial for a recoverable execution reason (iteration exhaustion, missing write evidence, failed write_file, or no verified final delta), the CLI may run exactly one tool-free recovery plan and one focused implementation retry capped at eight iterations. Policy denials, unsafe Git attribution, errors, and cancellation do not trigger retry.

After an agent pipeline run, /diff shows the most recent verified Git diff captured by a requires_change block (with status, status reason, verification warning, and recorded writes), and /changes summarizes per-block activity (role, status, duration, tool calls, evidence). Both commands read session-scoped state — cleared by /clear, overwritten by the next pipeline run, never persisted to disk.

Long sessions automatically drop stale tool-result messages once cfg.messages exceeds prune_after_messages (default 80), preserving the most recent prune_keep_recent (default 40) messages and never touching user/assistant/system messages. When a tool result is dropped, the matching tool_calls entry on its originating assistant message is stripped to prevent orphan references. Runs before context compaction every turn; emits a prune perf event only when at least one message was removed.

When a requires_change block completes on recorded write_file evidence but Git verification is unavailable, the manual-confirmation notice is carried on a dedicated verification field. The block's output stays untouched; the warning is rendered on the completion panel and passed to downstream blocks in a separate ## Verification section.

Agent Block runs use enabled intuition recall before the first block and display any recalled context. For medium-risk coding tasks with policy enforcement enabled, write and shell tools remain available subject to approval; high-risk tasks remain read-only.

The built-in code-change plan block may perform up to four local read-only inspection turns before planning, so implementation starts from observed Python paths instead of guessed project structure.

Model-Callable Tools

The model can call these tools during a conversation:

Files: read_file, read_pdf, render_pdf_pages, edit_file, write_file, list_directory, search_files, find_unique_anchor, batch_edit

Shell: run_shell

Web: web_search, web_fetch (requires Ollama Cloud + API key)

X: x_search uses optional xAI Grok OAuth for read/search and requires your XAI_CLIENT_ID. x_account_status, x_account_draft_post, x_account_draft_reply, x_account_post, x_account_reply, and x_account_post_action use the separate X API OAuth lane through xurl; write actions require explicit confirmation.

/x-account requires the official X API CLI, xurl, to be installed and authenticated separately. The CLI only runs xurl auth status for status checks and never reads ~/.xurl directly.

Memory: remember, append_lesson, update_user_profile

Multimodal: embed_text, vision_describe

Models: model_show, model_pull, model_copy, model_create, model_delete

Files and Git: read_file, read_pdf, render_pdf_pages, edit_file, write_file, list_directory, search_files, find_unique_anchor, batch_edit, git_status, git_diff

Harness: available_actions, harness_stats, harness_search, harness_read, harness_refresh, query_knowledge_graph

After /icl on, query_knowledge_graph reads the configured index-compute-lab ranked association index through its public query CLI. Set ALGO_CLI_INDEX_COMPUTE_LAB_ROOT to use a different local checkout.

write_file, run_shell, model_delete, and model_create require approval unless /auto is enabled. Safe mode blocks destructive shell patterns by default. Agent Blocks with requires_change = true are instructed prescriptively that file creation, edits, appends, and deletes must go through write_file; run_shell is restricted to read-only verification (status, tests, lint, diff, grep, ls). Shell-based file mutation (heredocs, output redirection, sed -i, Set-Content, Out-File, etc.) is not counted as evidence of a change, and the model is told to stop and report rather than route edits through shell when write_file is unavailable.

Agent Block runs automatically snapshot git status and tracked git diff around implementation blocks, so review and final blocks receive verified change evidence rather than relying only on model narrative.

Blocks without requires_change are not gated, but if they execute a successful write_file action or a shell command classified as mutating, the CLI captures read-only Git audit evidence and passes it to downstream blocks.

Harness Bridge

The CLI retrieves relevant records from a local index. The public built-in corpus is enabled by default; external agent stores require /harness external on. Indexing reads content but never executes external agent tools.

Default sources: packaged Algo CLI docs and skills, user-created ~/.algo_cli records, and explicit harness_roots.json entries.

Opt-in sources: Codex, Claude, OpenClaw, shared agents, Mercury, CLI Agent, Pi, and index-compute-lab.

Harness commands:

/harness status
/harness score
/harness compare
/harness refresh
/harness external status
/harness build-rust
/hsearch retrieval benchmark
/hread algo-cli:memory:algo-cli-memory-lifecycle-contract.md

/harness score grades Algo CLI's internal retrieval/runtime readiness. /harness compare recomputes the declared five-axis competitor matrix and applies ten stricter leader gates. It will not claim leadership from a dirty worktree, missing revision-pinned competitor evidence, local-only benchmarks, ties, or a second-place corrected score.

Rust Indexer (optional)

For faster cold-start index builds:

cd harness-indexer
cargo build --release

Native helpers are source-checkout features and are not bundled into the Python wheel. When built from a checkout, Algo CLI uses the Rust indexer for opted-in cold-start discovery only. Warm refreshes use the Python incremental scanner. Point to a custom binary:

export ALGO_CLI_HARNESS_INDEXER=/path/to/harness-indexer

Legacy OLLAMA_CLI_HARNESS_INDEXER is still accepted as a fallback.

Go Gateway (optional)

Exposes the harness index over localhost for bridge integrations:

cd harness-gateway
go run . -addr 127.0.0.1:8765

Endpoints: GET /healthz, GET /harness/stats, GET /harness/search, POST /supplemental/embed

Override: ALGO_CLI_GATEWAY_URL, ALGO_CLI_GATEWAY_BIN (legacy OLLAMA_CLI_* names are still accepted).

Configuration

Config is stored in ~/.algo_cli/ by default (data from ~/.ollama_cli is auto-copied with backup on first run). Runtime environment values load from ~/.algo_cli/env. Override with ALGO_CLI_CONFIG_DIR or ALGO_CLI_ENV_FILE. Legacy OLLAMA_CLI_* variables are still read for one release.

Variable	Purpose
ALGO_CLI_CONFIG_DIR	Override config directory
ALGO_CLI_ENV_FILE	Override runtime env file path (env is preferred; .env is supported as a fallback)
ALGO_CLI_MODEL	Default model
ALGO_CLI_THEME	Default theme (tokyo-night, catppuccin-mocha, dracula, nord, gruvbox, dolphie)
ALGO_CLI_GATEWAY_URL	Go gateway URL
ALGO_CLI_HARNESS_INDEXER	Optional Rust harness indexer binary
OPENAI_OAUTH_CLIENT_ID	Optional override for the bundled ChatGPT/Codex browser OAuth client
OPENAI_CODEX_CLIENT_ID	Optional override for the bundled Codex OAuth client
XAI_CLIENT_ID	Your authorized OAuth client ID for optional xAI subscription login; Algo CLI does not bundle one
OLLAMA_HOST	Local Ollama host
OLLAMA_API_KEY	Direct Ollama Cloud API/web tools key; not required for signed-in local :cloud models

Legacy OLLAMA_CLI_* equivalents are read for compatibility during the rebrand window.

Development

python -m pip install -e ".[dev]"

ruff check algo_cli tests
python scripts/check_public_release.py
python -m compileall -q algo_cli      # compile check
pytest tests --cov=algo_cli --cov-branch --cov-fail-under=57

The test suite stubs all model calls and runs against a temporary config directory — no running Ollama instance or network access required.

Optional native components:

# Rust indexer
cd harness-indexer
cargo fmt --check && cargo clippy --release -- -D warnings && cargo test --release

# Go gateway
cd harness-gateway
gofmt -l . && go vet ./... && go test ./...

CI runs Python on Linux, Windows, and macOS; validates the wheel and source distribution; and tests the Rust and Go helpers.

License

MIT — see LICENSE.