Skip to content
nijaruPublic

About

Experimental Rust coding-agent runtime with persistent, forkable sessions.

Resources

Stars

5 stars

Watchers

0 watching

Forks

Repository files navigation

Ion

Ion is an experimental Rust agent engine and coding application. One agent/Session engine serves headless CLI, terminal chat, stdio RPC and Rust hosts, including non-coding applications. The coding application provides filesystem, search, guarded editing, shell and web tools, with optional MCP and Code Mode. Conversations are saved in SQLite.

Status: unreleased v0. Everyday coding reliability and native terminal usability are not yet qualified; the TUI is not a recommended daily driver. Ion targets Pi-like capabilities and interaction with compact fx-like terminal styling. Source defines implemented behavior, not planned features.

Build or install

Use the toolchain in rust-toolchain.toml:

cargo build --locked -p ion
target/debug/ion --help

To install ion on your Cargo binary path:

cargo install --locked --path crates/ion-cli

The examples below use the installed ion. For a build-only checkout, replace it with target/debug/ion when running from the repository root.

Set up a model

First inspect the local model catalog and credential sources:

ion models
ion auth

Choose a provider ID and model ID from the catalog that you are authorized to use. Replace PROVIDER and MODEL below; catalog inclusion does not guarantee account access.

ion use PROVIDER MODEL
ion login PROVIDER
ion doctor

login takes an API key at a masked terminal prompt. Skip it if the route already has credentials through its supported environment variable or needs no key. auth shows sources without displaying secrets; doctor checks configuration offline. These setup commands do not send model requests. For a custom compatible endpoint, see ion use --help; supply the endpoint and wire format for your actual service rather than a catalog route.

Configuration, saved credentials, resources and Sessions use ~/.ion by default, or ION_HOME when set. Workspace .ion files are separate. Ion does not automatically migrate old XDG storage.

Use

After configuration, submit a request or open terminal chat. Model requests can incur provider charges:

ion --read-only run 'Summarize this project'
ion                                  # experimental terminal chat
ion --continue                       # reopen latest Session in this directory
ion -r                               # choose a saved Session

ion run 'PROMPT' runs headlessly; ion -p 'PROMPT' is shorthand. Use ion --json run 'PROMPT' for JSONL events or ion rpc for stdio JSONL control. Headless and RPC clients require a configured model and credentials. CLI options can precede a command but must apply to it; use ion --help and ion COMMAND --help for exact options. In chat, /help lists controls and /help keys shows effective bindings.

Permissions and recovery:

  • Coding commands run with your host permissions. Tool filters and --read-only restrict the model's loadout, not the host: explicit user shell and trusted executable commands remain available. They are not a sandbox or a per-call approval system.
  • Ctrl-C immediately requests cancellation of foreground work, including unanswered questions; it may wait for cleanup to join. While attached to a program, Ctrl-C goes to that program instead. See terminal controls.
  • Cancellation does not undo effects. Reopening does not restart interrupted work, and navigating, cloning or forking a conversation does not roll back files. Inspect unknown outcomes before asking to repeat a mutation.

Documentation

Develop

cargo fmt --all -- --check
cargo clippy --locked --workspace --all-targets --all-features -- -D warnings
cargo test --locked --workspace
cargo build --locked -p ion
scripts/smoke.sh

The smoke script exercises an offline built headless/reopen path. See AGENTS.md for project-specific development guidance and Rust embedding for library examples and API documentation.

Limitations

Durable storage and conservative effect recovery are implemented, but fully automatic service restart/wake, arbitrary dynamic extensions, provider coverage, broad ACP/editor integrations and model-backed daily-driver qualification are incomplete. Code Mode is optional; restart-safe guest reconstruction and full Pi Durable-level nested-call semantics are not yet established. Incompatible Session databases are rejected rather than migrated during unstable development. Rust APIs may change before release.

License

MIT. See LICENSE.

About

Experimental Rust coding-agent runtime with persistent, forkable sessions.

Resources

Stars

5 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages