horus-cli 0.1.0

A minimal terminal coding agent built with Horus
horus-cli-0.1.0 is not a library.
Visit the last successful build: horus-cli-0.6.12

Horus CLI

horus-cli is the reference terminal coding agent built with the horus framework. It owns the executable, setup and local configuration, and the Ratatui frontend; the agent loop and capabilities remain in the framework crate.

Run

Download the matching archive and checksum from GitHub Releases:

  • Apple Silicon macOS: aarch64-apple-darwin
  • x86_64 Linux: x86_64-unknown-linux-gnu

Verify with shasum -a 256 -c FILE.sha256, extract the archive, and put horus on your PATH. Rust users and other macOS or Linux architectures can build locally with Rust 1.89 or newer:

cargo install horus-cli

Run horus. To run from a source checkout:

cargo run -p horus-cli

The first interactive launch opens setup for a provider, model, optional middleware, and sandbox approval policy. Built-in providers are OpenAI by API key, OpenAI with ChatGPT login, Kimi, OpenRouter, Anthropic, and a configurable OpenAI-compatible Responses endpoint.

API-key providers use their standard environment variables:

export OPENAI_API_KEY=...
export MOONSHOT_API_KEY=...
export OPENROUTER_API_KEY=...
export ANTHROPIC_API_KEY=...

If a key is pasted into setup, Horus stores it in its local TOML configuration. ChatGPT login stores refreshable OAuth credentials in auth.json; it does not read or modify Codex CLI credentials. On Unix, Horus writes configuration and authentication files with owner-only permissions.

Local state

The first launch creates ~/.horus. It contains:

  • config.toml — model routes, middleware, sandbox, and checkpoint settings.
  • auth.json — ChatGPT credentials, when configured.
  • horus.sqlite3 — session checkpoints and catalog state.

The supported overrides are:

  • HORUS_CONFIG — an alternate configuration file.
  • HORUS_STATE_DIR — an alternate state directory.
  • HORUS_SESSION_ID — a session to resume at startup.

Each normal launch starts a fresh session. Use the middleware-provided /resume command to select an existing session when session middleware is enabled.

Terminal contributions

The TUI is a thin subscriber to the framework capability catalog:

  • Capabilities own their commands, status widgets, references, and capability-specific rendering.
  • / opens both CLI shell commands and commands contributed by framework capabilities.
  • $ references are contributed by skills middleware.
  • @ workspace-file completion belongs to the CLI because it is terminal composer behavior.

The CLI itself owns only shell lifecycle and presentation commands: /help, /login, /new, /clear, /model, /reasoning, /status, /interrupt, and /exit. /new starts a fresh session; /clear also clears the underlying terminal scrollback. The menu changes with the installed capabilities. Sending ordinary text while a turn is active steers the turn when steering middleware is installed.

The Sora-themed TUI uses the full terminal. The mouse wheel and Page Up/Page Down scroll the chat; Ctrl-T opens its full-screen transcript view. Arrow, page, and wheel input navigate an open preview; Up/Down and Ctrl-P/Ctrl-N navigate composer history.

The local command sandbox uses /usr/bin/sandbox-exec on macOS and bwrap on Linux. Linux must permit the selected bwrap binary to create user, PID, and network namespaces; AppArmor-restricted hosts need a matching Bubblewrap profile. The /permissions command changes the sandbox policy between approval prompts, no-prompt execution without network, and no-prompt execution with network. Bash may write only in the workspace and its private temporary directory in every mode. Command execution fails closed when the platform sandbox is unavailable.

License

Licensed under Apache-2.0. See NOTICE for upstream attribution.