README
¶
Ion
[!NOTE] Ion is an early preview. It can read, edit, and run commands in your working tree, but the core agent and TUI are still being hardened.
Ion is a terminal coding agent for working on codebases from your shell. It opens an interactive chat UI, gives the model a small set of coding tools, and keeps sessions available so you can resume work later.
Install
Ion requires Go 1.26 or newer.
From a local checkout:
go install ./cmd/ion
From GitHub:
go install github.com/nijaru/ion/cmd/ion@latest
Make sure Go's binary directory is on your PATH:
export PATH="$(go env GOPATH)/bin:$PATH"
Then start Ion:
ion
Provider Setup
The first interactive run opens the provider picker. Choose a provider, enter an API key when prompted, then choose a model.
Ion supports direct API-key providers and custom OpenAI-compatible endpoints.
OpenAI-compatible /v1 APIs are the usual interface for local model servers,
hosted gateways, and self-managed inference services.
Most users do not need a config file. Use ~/.ion/config.toml only for custom
endpoints, stable defaults, or provider settings you want outside the TUI.
Example custom/local endpoint:
# ~/.ion/config.toml
provider = "openai-compatible"
model = "qwen3.6:27b"
endpoint = "http://localhost:11434/v1"
context_limit = 70000
Example endpoint with an environment-backed token:
# ~/.ion/config.toml
provider = "openai-compatible"
model = "provider/model"
endpoint = "https://example.com/v1"
auth_env_var = "CUSTOM_API_KEY"
Runtime choices made in the TUI are stored in ~/.ion/state.toml. API keys
entered in Ion are stored in ~/.ion/credentials.toml.
Per-run overrides are also supported:
ION_PROVIDER=openai ION_MODEL=gpt-5.5 ion
ion --provider openai-compatible --model qwen3.6:27b
Usage
Start the TUI:
ion
Run a prompt and print the answer:
ion -p "summarize this project"
cat README.md | ion -p "summarize this"
ion --continue -p "what did we do last?"
ion --json -p "reply with ok"
Common TUI commands:
/help show commands and keys
/provider choose a provider
/login save an API key
/model choose a model
/thinking choose reasoning effort
/status show runtime status
/resume resume a previous session
/compact compact the current session
/quit exit
Development
go run ./cmd/ion
go test ./...
go vet ./...
scripts/smoke/tmux-minimal-harness.sh
Live provider smoke tests are gated behind environment variables and are not part of the default test run.
License
Directories
¶
| Path | Synopsis |
|---|---|
|
Package approval provides a transport-agnostic approval bridge for pausing framework operations until a host explicitly allows or denies them.
|
Package approval provides a transport-agnostic approval bridge for pausing framework operations until a host explicitly allows or denies them. |
|
Package audit provides append-only structured logging for security events.
|
Package audit provides append-only structured logging for security events. |
|
Package testing provides test utilities for agents built with canto.
|
Package testing provides test utilities for agents built with canto. |
|
cmd
|
|
|
ion
command
|
|
|
ion-tui-smoke
command
|
|
|
internal
|
|
|
agent
Package agent provides the core agent loop primitive for Ion.
|
Package agent provides the core agent loop primitive for Ion. |
|
Package llm defines Canto's provider-agnostic model interface.
|
Package llm defines Canto's provider-agnostic model interface. |
|
Package prompt builds model requests from durable session state.
|
Package prompt builds model requests from durable session state. |
|
Package session provides Canto's durable append-only conversation log.
|
Package session provides Canto's durable append-only conversation log. |
|
Package tool defines executable tool contracts and registry helpers.
|
Package tool defines executable tool contracts and registry helpers. |
|
mcp
Package mcp exposes Canto tools over the Model Context Protocol and adapts remote MCP tools back into Canto's tool registry.
|
Package mcp exposes Canto tools over the Model Context Protocol and adapts remote MCP tools back into Canto's tool registry. |
|
Package tracing provides OpenTelemetry instrumentation for ion agents.
|
Package tracing provides OpenTelemetry instrumentation for ion agents. |
|
Package workspace provides validated rooted filesystem access for workspace-aware agents and hosts.
|
Package workspace provides validated rooted filesystem access for workspace-aware agents and hosts. |