aictl

AI agent for your terminal and desktop + HTTP LLM proxy server — 74 built-in cloud models across 8 providers, plus any model available through Ollama, native GGUF inference via llama.cpp, or native MLX inference on Apple Silicon. Security-first by default.

Project website: aictl.app — source in website/.

CLI user guides: https://aictl.app/cli.html

[!NOTE]
The aictl is a general-purpose AI agent.
Dedicated coding capabilities may be added in the future. If you are looking for an AI agent specialized in software development today,
consider Claude Code, Codex, or opencode — they are purpose-built for that workflow.

💻 You can use aictl on your desktop...

...and in your terminal ⌨️

with the single configuration and feature parity for CLI and desktop app.

In addition, you can also use HTTP Server with LLM proxy with security features.

Install CLI

curl -sSf https://aictl.app/install.sh | sh

The installer downloads a prebuilt binary for your platform from the latest GitHub release and places it in ~/.local/bin/aictl. If aictl is already installed at ~/.cargo/bin/aictl (e.g. from a prior cargo install), the installer updates it in place at that location instead of the default ~/.local/bin/. Set AICTL_INSTALL_DIR to pick a different location explicitly. If no prebuilt binary exists for your platform, the installer falls back to building from source with cargo install.

Supported platforms

Prebuilt binaries are published for:

Native Windows is not supported — aictl depends on a POSIX shell (sh) and Unix tools (date, pbcopy, etc.) for its built-in tool calls. Windows users can run aictl inside WSL using the Linux binary, which works normally.

Other platforms (FreeBSD, other BSDs, uncommon Linux architectures) can still build from source via the cargo install fallback path, provided a Rust toolchain is available.

Prerequisites

Installing a prebuilt binary has no prerequisites beyond curl. Building from source (either via the installer fallback or manually) requires Rust (edition 2024).

From source

git clone [email protected]:pwittchen/aictl.git
cd aictl
cargo install --path crates/aictl-cli

To install with all features run:

cargo install --path crates/aictl-cli --features "gguf mlx redaction-ner"

This installs the aictl binary to ~/.cargo/bin/.

Build without installing

cargo build --release

The binary will be at target/release/aictl.

Optional feature flags

Native local-model inference is gated behind cargo features so a plain cargo build / cargo install keeps a lightweight default (no C++ toolchain or Metal Toolchain required). Opt in per backend:

Examples:

# GGUF only
cargo build --release --features gguf
cargo install --path crates/aictl-cli --features gguf

# MLX only (macOS Apple Silicon)
cargo build --release --features mlx
cargo install --path crates/aictl-cli --features mlx

# NER-backed redaction only (Layer C of the redaction pipeline)
cargo build --release --features redaction-ner
cargo install --path crates/aictl-cli --features redaction-ner

# All three (GGUF + MLX + NER-backed redaction)
cargo build --release --features "gguf mlx redaction-ner"
cargo install --path crates/aictl-cli --features "gguf mlx redaction-ner"

Without these features, the corresponding slash commands (/gguf, /mlx) and CLI flags (--pull-gguf-model, --pull-mlx-model, --pull-ner-model, etc.) still work for model management (download / list / remove); only the inference path is disabled, and trying to run a local model or enable NER-backed redaction prints a clear error telling you which feature to rebuild with.

The prebuilt binaries published on GitHub Releases (downloaded by install.sh) ship with --features gguf enabled on every platform — so one-liner installs get native GGUF inference out of the box where the platform supports it. The macOS Apple Silicon (aarch64) release additionally ships with --features mlx and includes a sibling mlx.metallib file alongside the binary (MLX needs the Metal library at runtime); every other platform's release contains just the aictl binary.

Build desktop app

The desktop frontend (aictl-desktop) is a Tauri v2 app with a Solid + Vite webview that reuses the same aictl-core engine as the CLI. It is macOS-only for the first release and is excluded from the workspace's default member set, so a bare cargo build / cargo lint / cargo test keeps working without Tauri's deps. Build it explicitly with -p aictl-desktop.

[!NOTE]
The desktop app is currently work in progress. Expect rough edges.

Prerequisites

• macOS 13.0 or newer (Apple Silicon or Intel).
• Rust (edition 2024).
• Node.js 18+ (for the webview bundle).
• Xcode Command Line Tools (xcode-select --install).
• cargo-tauri CLI: cargo install tauri-cli --version "^2.0".

Install webview dependencies (one-time)

cd crates/aictl-desktop/webview
npm install
cd -

Dev build

Hot-reloading dev workflow — Vite serves the webview at http://localhost:5173 and Tauri rebuilds the Rust side on save:

make desktop-dev
# equivalent to:
cd crates/aictl-desktop && cargo tauri dev --features gguf,mlx,redaction-ner

Alternatively, type-check the Rust side only (no webview, no window):

cargo build -p aictl-desktop

Or run the release binary against a pre-built webview bundle:

make desktop-run
# equivalent to:
cargo run --release -p aictl-desktop --features gguf,mlx,redaction-ner

Release build

Produces an optimized .app bundle and a .dmg installer under target/release/bundle/:

make desktop-build
# equivalent to:
cd crates/aictl-desktop && cargo tauri build --features gguf,mlx,redaction-ner

Outputs:

• target/release/bundle/macos/aictl.app — the application bundle.
• target/release/bundle/dmg/aictl_<version>_<arch>.dmg — the disk image.

Local builds are unsigned by default — Gatekeeper will block first launch. Right-click the app and choose Open to bypass, or remove the quarantine flag:

xattr -dr com.apple.quarantine /Applications/aictl.app

The official DMGs published to GitHub Releases are signed with a Developer ID and notarized by Apple — those open cleanly without any workaround.

The desktop reuses every ~/.aictl/ config file (sessions, agents, skills, MCP, hooks, plugins, audit log, stats) but pins its tool-call working directory to AICTL_WORKING_DIR_DESKTOP — independent of the CLI's AICTL_WORKING_DIR, so launching the desktop won't silently retarget CLI tool calls. See crates/aictl-desktop/README.md for the layout and current status.

HTTP server (aictl-server)

A second binary in this workspace, aictl-server, exposes the same provider catalogue over an OpenAI-compatible HTTP endpoint with redaction, prompt-injection blocking, audit, and a master-key gate. Pure proxy — no agent loop, no tools, no agents/skills/sessions. See SERVER.md for the full reference.

curl -fsSL https://aictl.app/server/install.sh | sh
aictl-server     # listens on 127.0.0.1:7878 by default; prints master key on first launch
aictl --serve    # convenience shortcut from the CLI; forwards trailing args after `--`

Use aictl-server as the upstream

The CLI can also point at an aictl-server instance instead of talking to each provider directly. With this set, the operator configures provider keys (LLM_OPENAI_API_KEY, LLM_ANTHROPIC_API_KEY, …) once on the server, and every CLI host carries only a single master key.

aictl --client-url http://127.0.0.1:7878 --client-master-key sk-aictl-…

Or persist it:

# In ~/.aictl/config — note the AICTL_CLIENT_* prefix (the CLI's view).
# The server's own AICTL_SERVER_MASTER_KEY is a separate key; the same
# machine can host both roles without ambiguity.
AICTL_CLIENT_HOST=http://127.0.0.1:7878
AICTL_CLIENT_MASTER_KEY=sk-aictl-…

AICTL_CLIENT_MASTER_KEY participates in the same /keys lock/unlock/clear lifecycle as the provider keys, so it can move into the OS keyring like any other secret. Local providers (Ollama, GGUF, MLX) bypass the server unconditionally — the proxy hop would be pointless.

Uninstall

Binary release (installed via install.sh)

The install script places the binary at ~/.local/bin/aictl (or $AICTL_INSTALL_DIR if you set it). Remove it with:

rm ~/.local/bin/aictl

From source (installed via cargo install)

Cargo tracks its own installs, so the clean way is:

cargo uninstall aictl

This removes ~/.cargo/bin/aictl. If cargo uninstall doesn't find it (e.g. installed under a different crate name), delete the binary directly:

rm ~/.cargo/bin/aictl

Remove configuration and data (optional)

aictl stores all state under ~/.aictl/ — config file, saved agents, saved sessions. To wipe it completely:

rm -rf ~/.aictl

Skip this step if you plan to reinstall and want to keep your API keys, agents, and session history.

Usage

aictl [--version] [--update] [--uninstall] [--config] [--provider <PROVIDER>] [--model <MODEL>] [--message <MESSAGE>] [--format <FORMAT>] [--auto] [--quiet] [--audit-file <PATH>] [--cwd <PATH>] [--unrestricted] [--incognito] [--agent <NAME>] [--list-agents] [--pull-agent <NAME>] [--skill <NAME>] [--list-skills] [--pull-skill <NAME>] [--force] [--session <ID|NAME>] [--list-sessions] [--clear-sessions] [--lock-keys] [--unlock-keys] [--clear-keys] [--pull-gguf-model <SPEC>] [--list-gguf-models] [--remove-gguf-model <NAME>] [--clear-gguf-models] [--pull-mlx-model <SPEC>] [--list-mlx-models] [--remove-mlx-model <NAME>] [--clear-mlx-models] [--balance] [--list-plugins] [--list-hooks] [--list-mcp] [--mcp-server <NAME>]

Omit --message to enter interactive REPL mode with persistent conversation history.

REPL Commands

The interactive REPL supports slash commands:

Any unrecognized /<name> that matches a saved skill (see Skills below) runs that skill for the next turn: /<skill-name> runs it with a default trigger, /<skill-name> <task> routes <task> as the user message.

Press Esc during any LLM call or tool execution to interrupt the operation and return to the prompt. Conversation history is rolled back so the interrupted turn has no effect.

Parameters

Only --version (-v) and --help (-h) have short flags. All other options use long form only, by convention.

CLI flags take priority over config file values.

Sessions

In interactive mode, each REPL run is a session. A new uuid is generated at startup and the conversation is persisted to ~/.aictl/sessions/<uuid> as JSON after every agent turn and compaction. Session names (optional, unique) are stored in ~/.aictl/sessions/.names. On exit, the session uuid (and name, if set) is printed.

Use /session to show current session info, assign a readable name, browse saved sessions (load or delete with confirmation), or clear all sessions. Pass --session <uuid|name> to resume an existing session on startup. Incognito mode (--incognito or AICTL_INCOGNITO=true) runs the REPL without creating or saving any session file; /session is disabled and displays a notice.

Agents

Agents are reusable system prompt extensions that specialize the LLM for dedicated tasks or behaviors. Agent prompts are stored as plain text files in ~/.aictl/agents/.

Use /agent to open the agent menu:

• Create agent manually — enter a name and type or paste the agent prompt text directly
• Create agent with AI — provide a name and brief description; the LLM generates the full agent prompt
• Browse official agents — browse the live catalogue of curated agents shipped in the aictl repo (see "Official catalogue" below), preview them, and pull the ones you want to ~/.aictl/agents/
• View all agents — browse saved agents, view their prompt, load an agent, or delete it
• Unload agent — remove the currently loaded agent (only shown when one is loaded)

Agents can also be loaded from the command line with --agent <name>, which works in both single-shot and interactive modes.

Agent names may contain only letters, numbers, underscores, and dashes. When an agent is loaded, its prompt is appended to the system prompt and the agent name appears in magenta brackets before the input prompt (e.g. [my-agent] ❯).

Official catalogue

aictl ships with a curated set of first-party agents (e.g. researcher, software-architect, critic, security-auditor, psychologist) that live in the project's GitHub repo under .aictl/agents/ — not bundled into the binary. New catalogue agents are available the moment they land on master, no release needed.

Pull agents from the catalogue in two ways:

• From the REPL, /agent → Browse official agents. Agents are grouped by category; each row shows [ ] (not pulled), [✓] (matches upstream), or [↑] (upstream differs). Press v to preview an agent's prompt before pulling, p / Enter to pull.
• From the shell, aictl --pull-agent <name> downloads a single agent. Add --force to overwrite an existing local file without prompting.

Catalogue agents carry source: aictl-official in their frontmatter; both /agent and --list-agents render an [official] badge so you can tell at a glance which agents came from the catalogue and which you wrote yourself. Users can edit or delete pulled agents freely — there is nothing special about them on disk. Public-repo reads are unauthenticated (≈60 requests/hour), which is plenty for browse-then-pull; errors are reported in the REPL without crashing the session.

Skills

Skills are markdown playbooks invoked on demand for a single turn — unlike agents, which persist for the whole session. A skill encodes a repeatable procedure ("run the commit workflow", "review the pending diff") that the LLM should follow this one time; after the turn completes, the skill is gone. Skills live under ~/.aictl/skills/<name>/SKILL.md (overridable via AICTL_SKILLS_DIR).

Each SKILL.md starts with YAML frontmatter (name, description) followed by the markdown body:

---
name: commit
description: Commit staged changes with a clear, project-style message.
---

When the user asks you to commit:
1. Run `git status` and `git diff --cached` to see what's staged.
2. ...

Use /skills to open the skill menu:

• Create skill manually — enter a name and description, then type or paste the body
• Create skill with AI — provide a name and one-line description; the LLM drafts the body
• Browse official skills — browse the live catalogue of curated skills shipped in the aictl repo (see "Official catalogue" below), preview them, and pull the ones you want to ~/.aictl/skills/<name>/SKILL.md
• View all skills — browse saved skills with view / invoke / delete actions

Invoke a skill directly by typing /<skill-name> at the REPL prompt. /commit runs the skill with a default trigger so the body alone drives the turn; /commit review the staged diff routes the trailing text as the user message. --skill <name> works the same way in single-shot and REPL modes. --list-skills prints saved skills and exits.

Skill names may contain only letters, numbers, underscores, and dashes and must not collide with a built-in slash command (e.g. help, exit, agent) — such names are rejected at save time. The skill body is merged into the base system prompt for the turn (rather than sent as a separate system message) so every provider, including those that accept only a single top-level system field, sees the skill alongside the tool catalog.

Official catalogue

aictl ships with a curated set of first-party skills that live in the project's GitHub repo under .aictl/skills/ — not bundled into the binary. New catalogue skills are available the moment they land on master, no release needed.

Pull skills from the catalogue in two ways:

• From the REPL, /skills → Browse official skills. Skills are grouped by category; each row shows [ ] (not pulled), [✓] (matches upstream), or [↑] (upstream differs). Press v to preview a skill's body before pulling, p / Enter to pull.
• From the shell, aictl --pull-skill <name> downloads a single skill. Add --force to overwrite an existing local file without prompting.

Catalogue skills carry source: aictl-official in their frontmatter; both /skills and --list-skills render an [official] badge so you can tell at a glance which skills came from the catalogue and which you wrote yourself. Users can edit or delete pulled skills freely — there is nothing special about them on disk. Public-repo reads are unauthenticated (≈60 requests/hour), which is plenty for browse-then-pull; errors are reported in the REPL without crashing the session.

Plugins

Plugins are user-installed external tools that extend the agent without forking the repo. A plugin is a directory under ~/.aictl/plugins/<name>/ containing a plugin.toml manifest and an executable entrypoint (any language — shell script, Python, compiled binary, anything that reads stdin and writes stdout).

~/.aictl/plugins/
└── kubectl_query/
    ├── plugin.toml
    └── run            # executable; chmod +x

plugin.toml:

name = "kubectl_query"
version = "0.1.0"
description = "Query a Kubernetes cluster. Input: 'get|describe|logs <resource> [name]'."
entrypoint = "run"           # relative path inside the plugin dir; default "run"
requires_confirmation = true # keep true unless the plugin is purely read-only
timeout_secs = 30            # optional; falls back to AICTL_SECURITY_SHELL_TIMEOUT
schema_hint = """
First line: subcommand (get|describe|logs)
Second line: resource type
Third line (optional): resource name
"""

Wire protocol:

• stdin — the raw <tool>…</tool> body the LLM emitted, exactly as it would be passed to a built-in tool. No JSON framing.
• stdout — the result string returned to the LLM verbatim (after <tool> tag escaping).
• exit code — 0 for success; non-zero is reported back to the LLM as [exit N] <stderr>. Chatty stderr on success is suppressed.
• environment — same scrubbed env that exec_shell uses (secrets / _KEY / _TOKEN / _PASSWORD stripped).
• working directory — pinned to the security CWD jail.

Plugins are gated behind AICTL_PLUGINS_ENABLED=true (default false) — third-party code does not auto-load. Discovery happens once at startup; restart aictl to pick up new plugins. A malformed manifest, missing entrypoint, or symlink that escapes the plugin directory causes that single plugin to be skipped with a stderr warning, never a startup failure.

CLI surface:

• aictl --list-plugins — non-interactive listing (name, description, location).
• /plugins (REPL) — list manifests, view a plugin's plugin.toml, toggle the master switch, show the plugins directory.

The standard security gate (security::validate_tool) runs before dispatch, so AICTL_SECURITY_DISABLED_TOOLS can disable a plugin name exactly like a built-in tool, the confirmation prompt fires unchanged, and --unrestricted bypasses validation just as it does for built-ins. To silence one plugin without touching its manifest, add it to AICTL_PLUGINS_DISABLED=foo,bar.

A reference echo_back plugin lives at examples/plugins/echo_back/ — copy the directory to ~/.aictl/plugins/echo_back/ and set AICTL_PLUGINS_ENABLED=true to try it.

Hooks

Hooks are user-defined shell commands the harness runs at lifecycle events. Use them for harness-level automation that does not belong in an agent prompt — running cargo fmt after every edit, blocking specific shell commands, snapshotting the transcript before compaction, or mirroring desktop notifications to a webhook.

Hooks live in ~/.aictl/hooks.json (override the path with AICTL_HOOKS_FILE):

{
  "PreToolUse": [
    { "matcher": "exec_shell", "command": "echo seen", "timeout": 30 }
  ],
  "PostToolUse": [
    { "matcher": "edit_file|write_file", "command": "cargo fmt --message-format short 2>&1 | head -c 2000" }
  ],
  "Stop": [
    { "matcher": "*", "command": "date '+turn ended at %H:%M:%S' >> /tmp/aictl-hook.log" }
  ]
}

Each hook is { matcher, command, timeout, enabled }. matcher is a glob over the tool name (exec_shell, read_*, edit_file|write_file, mcp__*__*) for tool events, or * for non-tool events. command runs via sh -c in the security working directory with a scrubbed env. timeout defaults to 60 seconds; enabled defaults to true.

Supported events:

Each hook receives a JSON payload on stdin (event, session_id, cwd, plus tool / prompt / notification / trigger depending on the event) and may return JSON on stdout to influence the harness:

Exit code 2 is shorthand for {"decision":"block","reason":"<stderr>"}. Failures (spawn error, timeout, non-2 nonzero exit) are logged to stderr and treated as "continue" so a broken hook can't wedge the agent loop.

Hooks are harness behavior, not LLM behavior — --unrestricted does not bypass them. Automated rules like "always run cargo fmt after edit_file" belong here, not in agent prompts or memory.

CLI surface:

• aictl --list-hooks — non-interactive listing (event, matcher, command, status).
• /hooks (REPL) — view all hooks grouped by event, toggle individual entries, test-fire a hook with a synthetic payload, or reload the file from disk.

A reference hooks.json with one example per event (all enabled: false so they don't fire until you flip them on) lives at examples/hooks.json.

MCP servers

aictl can connect to Model Context Protocol servers and merge their tools into the agent loop alongside built-ins and plugins. This unlocks the existing MCP ecosystem — filesystem, git, GitHub, Postgres, Slack, and dozens of others — without aictl having to integrate each one individually. Three transports are supported — stdio (spawn a local process), http (modern Streamable HTTP), and sse (legacy HTTP+SSE) — and the tools capability is wired up; resources and prompts are still on the roadmap.

Servers are declared in ~/.aictl/mcp.json (override the path with AICTL_MCP_CONFIG) in a shape compatible with Claude Desktop:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/Documents"],
      "enabled": true,
      "timeout_secs": 30
    },
    "github": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "ghcr.io/github/github-mcp-server"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${keyring:GITHUB_TOKEN}" }
    },
    "remote": {
      "transport": "http",
      "url": "https://mcp.example.com/v1",
      "headers": { "Authorization": "${keyring:MCP_REMOTE_TOKEN}" },
      "enabled": true,
      "timeout_secs": 30
    }
  }
}

Per-entry fields:

• stdio (default) — command + args (resolved via PATH, no shell), optional env, enabled, timeout_secs.
• http / sse — set transport: "http" (Streamable HTTP) or "sse" (HTTP+SSE) and supply url, optional headers, enabled, timeout_secs.

Both env (stdio) and headers (remote) values may use ${keyring:NAME} to pull a secret from the system keyring instead of checking it into the file. The whole subsystem is gated behind AICTL_MCP_ENABLED=true (default false) — third-party server processes do not auto-spawn. Remote URLs are validated by a hostname allow/deny gate (AICTL_MCP_ALLOW_HOSTS, AICTL_MCP_DENY_HOSTS) and require HTTPS unless AICTL_MCP_ALLOW_HTTP=true.

At startup, every enabled server is spawned in parallel, the JSON-RPC initialize handshake completes, and the server's tools/list response is merged into the agent loop's catalogue. Each tool is reachable as mcp__<server>__<tool> and the model invokes it like any built-in:

<tool name="mcp__filesystem__read_file">
{"path": "/Users/me/Documents/notes.md"}
</tool>

The body is a JSON object that matches the tool's input schema (the schema is appended to the system prompt so the model formats calls correctly). Failed servers are recorded in ServerState::Failed and never abort startup — a single broken entry can't take down the rest of the catalogue.

Security model:

• Every MCP call passes through the same security::validate_tool gate as built-ins. AICTL_SECURITY_DISABLED_TOOLS accepts qualified MCP names (mcp__github__create_issue).
• AICTL_MCP_DENY_SERVERS=github,slack blocks every tool from listed servers, even when the master switch is on.
• Outbound redaction runs on the entire message stream regardless of transport, so detected secrets never reach the server.
• The CWD jail does not apply — MCP servers run in their own process with their own privileges. Users who want strict isolation should keep AICTL_MCP_ENABLED=false or curate the server list aggressively.

CLI / REPL surface:

• aictl --list-mcp — non-interactive listing (server name, state, tool count, command).
• aictl --mcp-server <name> — restrict this session to only the named server (every other configured server is force-disabled for the process; not persisted).
• /mcp (REPL) — list servers, browse per-server tool catalogue with input schemas, toggle the master switch, show the config path.
• /info and the welcome banner show MCP server / tool counts when enabled.

A bundled tiny_add smoke-test server (Python, ~70 lines, exposes one add tool) lives at examples/mcp/tiny_add/server.py and a fully-annotated example config at examples/mcp.json.

Configuration

Configuration is loaded from ~/.aictl/config. This is a single global config file.

Additionally, aictl loads a project prompt file from the current working directory (default: AICTL.md). If present, its contents are appended to the system prompt, allowing per-project instructions for the agent. The filename can be customized via AICTL_PROMPT_FILE in ~/.aictl/config. When the configured/default file is missing, aictl falls back to CLAUDE.md and then AGENTS.md so existing project instructions for other tools are reused automatically; the fallback chain can be disabled with AICTL_PROMPT_FALLBACK=false.

The quickest way to get started is the interactive wizard:

aictl --config

It walks you through selecting a provider, model, and entering API keys. You can also edit ~/.aictl/config manually at any time.

Basic configuration

You need to configure API key for the provider and model you want to use. AICTL_MEMORY and AICTL_INCOGNITO params are optional.

API keys

FIRECRAWL_API_KEY is optional and is needed only if you want to use search_web tool.

Not all API keys are required. You need to provide only those, for which you set AICTL_PROVIDER and AICTL_MODEL.

If you want to use multiple LLM providers, then you need to provide appropriate keys.

Where to get API keys

Each provider issues API keys through its own developer console. Sign up, create a key, then paste it into ~/.aictl/config (or run aictl --config).

Ollama, native GGUF, and native MLX run locally and require no API key.

Secure key storage (system keyring)

By default, API keys live as plain text in ~/.aictl/config. aictl can also store them in the OS-native keyring — macOS Keychain or Linux Secret Service (gnome-keyring / KWallet via D-Bus) — and reads them transparently from whichever store has them.

The active backend appears in the welcome banner (keys: Keychain (2 locked · 1 plain · 0 both)) and /security shows the per-key location.

Migration is done from inside the REPL via the /keys interactive menu:

• lock keys — copies every plain-text key found in ~/.aictl/config into the system keyring and removes the plain-text copy
• unlock keys — copies every keyring entry back into ~/.aictl/config and deletes it from the keyring
• clear keys — removes the keys from both stores (asks for confirmation)

The same operations are available as one-shot CLI flags: --lock-keys, --unlock-keys, --clear-keys.

When the keyring backend is unavailable (e.g. headless Linux without a Secret Service daemon), aictl falls back to plain-text storage automatically and the banner shows keys: plain text in yellow.

Security configuration (optional)

Create ~/.aictl/config (see .aictl/config in this repo for the reference):

AICTL_PROVIDER=anthropic
AICTL_MODEL=claude-sonnet-4-20250514
LLM_ANTHROPIC_API_KEY=sk-ant-...
FIRECRAWL_API_KEY=fc-...

The file format supports comments (#), quoted values, and optional export prefixes.

Providers

aictl supports eleven LLM providers — eight remote APIs plus Ollama, native GGUF inference via llama.cpp, and native MLX inference on Apple Silicon:

OpenAI

Requires LLM_OPENAI_API_KEY. Supported models with cost estimates (input/output per 1M tokens):

GPT-5.2, GPT-5.4, and GPT-5.5 use dual-tier pricing that doubles above the 272K context threshold; the table shows the short-context rates. The cost meter in aictl always reports the short-context price.

Anthropic

Requires LLM_ANTHROPIC_API_KEY. Supported models with cost estimates (input/output per 1M tokens):

Google Gemini

Requires LLM_GEMINI_API_KEY. Supported models with cost estimates (input/output per 1M tokens):

Gemini 3.1 Pro uses dual-tier pricing that doubles above a 200K context threshold; the table shows the short-context rates. gemini-2.0-flash has been removed from the model list because Google is shutting it down on June 1, 2026.

xAI Grok

Requires LLM_GROK_API_KEY. Supported models with cost estimates (input/output per 1M tokens):

Grok 4 Fast and Grok 4.20 ship with a 2M-token context window, the largest available across frontier models. Grok 4.3 (released April 30, 2026) is the new flagship at a 1M-token context window — pricing doubles above the 200K input threshold.

Mistral

Requires LLM_MISTRAL_API_KEY. Supported models with cost estimates (input/output per 1M tokens):

DeepSeek

Requires LLM_DEEPSEEK_API_KEY. Supported models with cost estimates (input/output per 1M tokens):

deepseek-chat and deepseek-reasoner are now legacy aliases that route to deepseek-v4-flash upstream — they remain in the catalog for backward compatibility.

Kimi

Requires LLM_KIMI_API_KEY. Supported models with cost estimates (input/output per 1M tokens):

Z.ai

Requires LLM_ZAI_API_KEY. Supported models with cost estimates (input/output per 1M tokens):

Ollama

Ollama runs models locally — no API key required. Install Ollama from ollama.com, pull a model, and start the server:

ollama pull llama3.2
ollama serve

Then configure aictl to use it:

AICTL_PROVIDER=ollama
AICTL_MODEL=llama3.2:latest

Available models are detected automatically from your local Ollama instance via the REST API. The /model command shows only models you have pulled locally. If Ollama is not running, it will not appear in the model menu.

By default, aictl connects to http://localhost:11434. To use a different address, set LLM_OLLAMA_HOST in ~/.aictl/config.

All Ollama models are free (self-hosted), so cost estimation shows $0.00.

Any model string can be passed via --model; cost estimation uses pattern matching on the model name and falls back to zero if unrecognized.

Native GGUF (llama.cpp) — experimental

Experimental. Native GGUF inference is a new, work-in-progress feature. It runs, it works, and it talks to the same tools the API providers do — but expect rough edges: small models struggle with tool-call formatting, chat templates are hard-coded to ChatML (so some models respond in a less natural style than their native template would produce), generation parameters are fixed, and performance tuning (GPU offload, context reuse across turns, speculative decoding) has not been wired up yet. The API-provider path remains the recommended default for day-to-day use. Please report issues at github.com/pwittchen/aictl/issues.

aictl can run GGUF models in-process via llama-cpp-2 — no Ollama server required. By default no local models are available; they must be downloaded explicitly by the user, one at a time, into ~/.aictl/models/gguf/.

Native inference is gated behind the gguf cargo feature. Prebuilt binaries published on GitHub Releases (the ones install.sh downloads) ship with --features gguf enabled, so users who install via the one-liner get native GGUF inference out of the box — no extra steps required.

When building from source, the gguf feature is off by default to keep a plain cargo install aictl / cargo build working without a C/C++ toolchain. Opt in explicitly:

cargo install --path crates/aictl-cli --features gguf
# or
cargo build --release --features gguf

Building with --features gguf requires cmake and a working C/C++ compiler (Xcode Command Line Tools on macOS, build-essential on Debian/Ubuntu). The install-script fallback path (cargo install --git ..., triggered when no prebuilt binary exists for your platform) does not pass --features gguf and will therefore produce a binary without native inference — in that case, rebuild manually with the command above.

Model management (works in every build, even without --features gguf):

# Pull a GGUF model from Hugging Face
aictl --pull-gguf-model hf:bartowski/Llama-3.2-3B-Instruct-GGUF/Llama-3.2-3B-Instruct-Q4_K_M.gguf

# Shorthand form
aictl --pull-gguf-model bartowski/Llama-3.2-3B-Instruct-GGUF:Llama-3.2-3B-Instruct-Q4_K_M.gguf

# Direct URL
aictl --pull-gguf-model https://example.com/path/model.gguf

# List, remove, clear
aictl --list-gguf-models
aictl --remove-gguf-model Llama-3.2-3B-Instruct-Q4_K_M
aictl --clear-gguf-models

Inside the REPL, /gguf opens an interactive menu with the same operations (view downloaded / pull / remove / clear all). Downloads stream to ~/.aictl/models/gguf/<name>.gguf.part with a progress bar and are atomically renamed on completion, so an interrupted download never leaves a half-written model in place.

Once a model is downloaded it appears in the /model picker under the Native GGUF header, alongside Ollama models. Configure it as the default:

AICTL_PROVIDER=gguf
AICTL_MODEL=Llama-3.2-3B-Instruct-Q4_K_M

Inference runs on a tokio::spawn_blocking task, so it doesn't block the async runtime. Cost always shows $0.00. Messages are flattened into a ChatML-style prompt, which works well for modern instruction-tuned models; per-model chat templates may be added later. If you try to use a GGUF model in a build without --features gguf, aictl prints a clear error telling you to rebuild.

Tested GGUF models

The following models have been verified end-to-end (download, load, inference, tool calls) via the /gguf pull menu's predefined catalog:

Native MLX (Apple Silicon) — experimental

Experimental. Native MLX inference is a new feature limited to macOS on Apple Silicon (aarch64). Architecture coverage is currently Llama-family — Llama 3.x, Qwen 2.5, Mistral 7B v0.3, DeepSeek-R1 Distill Qwen — plus Gemma 2. Phi-3.5 and MoE models are rejected with a clear error. Llama 3.1/3.2 RoPE scaling is not yet applied (quality degrades past ~8K context), top-p sampling is omitted (temperature only), and the chat-template renderer falls back to ChatML when the per-model jinja template fails to render. Please report issues at github.com/pwittchen/aictl/issues.

aictl can run MLX models in-process via mlx-rs — no Python, no mlx_lm, no separate server. Quantized 4-bit weights from the mlx-community Hugging Face organization are loaded directly via safetensors. By default no local MLX models are available; they must be downloaded explicitly by the user into ~/.aictl/models/mlx/<name>/.

The macOS Apple Silicon prebuilt binary on GitHub Releases ships with --features mlx enabled and includes a sibling mlx.metallib file placed next to the binary at install time (MLX's first runtime fallback is <exec_dir>/mlx.metallib). Other platform releases contain only the aictl binary — they don't support MLX.

Native inference is gated behind the mlx cargo feature. When building from source, the mlx feature is off by default. Opt in explicitly (Apple Silicon only):

cargo install --path crates/aictl-cli --features mlx
# or
cargo build --release --features mlx

Building with --features mlx requires the Xcode Metal Toolchain (full Xcode, not just the Command Line Tools). Install via Xcode → Settings → Components, or xcodebuild -downloadComponent MetalToolchain. Verify with xcrun --find metal.

Model management (works in every build, even without --features mlx and even on non-Apple-Silicon hosts):

# Pull an MLX model from Hugging Face (mlx-community)
aictl --pull-mlx-model mlx:mlx-community/Llama-3.2-3B-Instruct-4bit

# Shorthand form
aictl --pull-mlx-model mlx-community/Qwen2.5-7B-Instruct-4bit

# List, remove, clear
aictl --list-mlx-models
aictl --remove-mlx-model mlx-community__Llama-3.2-3B-Instruct-4bit
aictl --clear-mlx-models

Inside the REPL, /mlx opens an interactive menu with the same operations plus a curated catalog of popular mlx-community repos. Downloads stream multi-file safetensors directories with a per-file progress bar.

Once a model is downloaded it appears in the /model picker under the MLX (Apple Silicon) header. Configure it as the default:

AICTL_PROVIDER=mlx
AICTL_MODEL=mlx-community__Llama-3.2-3B-Instruct-4bit

Inference runs on a tokio::spawn_blocking task, so it doesn't block the async runtime. Cost always shows $0.00. If you try to use an MLX model in a build without --features mlx, or on a non-Apple-Silicon host, aictl prints a clear error explaining the constraint.

Tested MLX models

The following models have been verified end-to-end (download, load, inference, tool calls) on Apple Silicon:

Cost estimates

The per-token tables above tell you what each model charges; they don't tell you what a realistic workday actually costs. For that, see LLM_PRICING.md — it models two usage patterns (chat assistant and coding agent) and reports daily and monthly totals for every model in the catalog.

The headline numbers for intensive use (150 chat turns/day or 50 coding tasks/day, 22 working days/month, cached pricing):

A few things worth knowing before you budget:

• Intensive coding agent use is roughly 60× more expensive than chat use on any given model, because the agent loop re-sends the growing conversation history each iteration and produces long, code-heavy outputs. Tool call count is not the dominant factor.
• Prompt caching cuts costs roughly in half, but the "cached" column is only reliable for Anthropic — aictl explicitly writes to Anthropic's prompt cache via cache_control markers. OpenAI, Gemini, Grok, DeepSeek, and Kimi cache automatically server-side, so you'll hit cached rates during sustained sessions but not after idle gaps longer than the provider's TTL (typically 5–10 minutes). Z.ai GLM and Mistral have no cache handling in aictl, so they always bill at the full rate.
• The cost meter that aictl prints after every turn reflects actual cached vs. fresh tokens from each provider's response, so it's more accurate than any estimate. If you want to know what your specific workload really costs, run a few typical sessions and watch the per-turn summary.

Agent Loop & Tool Calling

aictl runs an agent loop: the LLM can invoke tools, see their results, and continue reasoning until it produces a final answer.

By default, every tool call requires confirmation (y/N prompt). Use --auto to skip confirmation and run autonomously.

Available tools:

Image capabilities by provider

The read_image (vision/analysis) and generate_image tools depend on provider support:

Image generation fallback: generate_image auto-selects a provider based on available API keys. The active provider is tried first (if it supports generation), then falls back through OpenAI, Gemini, and Grok in order. This means you can generate images even when your active chat provider (e.g. Anthropic or Mistral) doesn't offer a generation API — as long as you have at least one of LLM_OPENAI_API_KEY, LLM_GEMINI_API_KEY, or LLM_GROK_API_KEY configured.

The tool-calling mechanism uses a custom XML format in the LLM response text (not provider-native tool APIs):

<tool name="exec_shell">
ls -la /tmp
</tool>

The agent loop runs for up to 20 iterations. LLM reasoning is printed to stderr; the final answer goes to stdout. Token usage, estimated cost, and execution time are always displayed after each response.

Security

All tool calls pass through a configurable security policy (crates/aictl-core/src/security.rs) before execution. By default:

• Shell command blocking: dangerous commands are blocked (rm, sudo, dd, mkfs, nc, etc.). Command substitution ($(...), backticks) is blocked. Compound commands (|, &&, ||, ;) are split and each segment is validated independently.
• CWD jail: file tools (read_file, write_file, remove_file, edit_file, create_directory, list_directory, search_files, find_files) can only operate within the working directory. Path traversal via .. is defeated by canonicalization.
• Blocked paths: sensitive paths are always blocked (~/.ssh, ~/.gnupg, ~/.aictl, ~/.aws, ~/.config/gcloud, /etc/shadow, /etc/sudoers).
• Environment scrubbing: shell subprocesses receive a clean environment — vars matching *_KEY, *_SECRET, *_TOKEN, *_PASSWORD are stripped so API keys cannot leak.
• Shell timeout: commands are killed after 30 seconds (configurable).
• Write size limit: file writes are capped at 1 MB (configurable).
• Output sanitization: tool results are sanitized to prevent prompt injection via <tool> tags.
• Injection guard: user prompts are scanned before being sent to the LLM. Inputs containing instruction-override phrases ("ignore previous instructions", "disable security", etc.) or forged role/tool tags (<tool …>, <|system|>, ### System:, etc.) are blocked with a clear error. Disable with AICTL_SECURITY_INJECTION_GUARD=false.
• Audit log: every tool invocation appends one JSON line to ~/.aictl/audit/<session-id> (JSONL) with timestamp, tool name, truncated input, and an outcome tag (executed + result_summary, denied_by_policy + reason, denied_by_user, disabled, duplicate) — separate from session history so a reviewer can reconstruct exactly what the model ran. The filename mirrors the session file under ~/.aictl/sessions/. Skipped in incognito mode and single-shot runs. Disable with AICTL_SECURITY_AUDIT_LOG=false.
• Sensitive-data redaction (opt-in): every outbound message body can be screened for credentials and PII before it reaches a remote provider. Enable with AICTL_SECURITY_REDACTION=redact to swap matches for [REDACTED:<KIND>] on the wire, or =block to abort the turn on any hit. Layer A: regex detectors for API keys (OpenAI / Anthropic / Google / GitHub / Stripe / Slack / HuggingFace / Groq), AWS access keys, JWTs (with base64-header sanity check), PEM private keys, DB/AMQP connection strings, emails, context-gated phones, credit cards (Luhn), IBANs (mod-97). Layer B: Shannon-entropy scanner for opaque tokens. Layer C (optional redaction-ner cargo feature + pulled GLiNER model): person / location / organization detection. User-supplied AICTL_REDACTION_EXTRA_PATTERNS and AICTL_REDACTION_ALLOW tune the detectors. Local providers (Ollama / GGUF / MLX) bypass by default. Every redaction event lands in the audit log; the persisted session file always keeps the user's original text.

Security denials are returned to the LLM as tool results (displayed in red) so it can adapt. Use --unrestricted to disable all security checks. Individual settings are configurable via AICTL_SECURITY_* keys in ~/.aictl/config. The audit log and redaction layer are observability and privacy controls, not tool-call enforcement, so --unrestricted leaves them running unless the config key turns them off.

Examples

# With defaults configured in ~/.aictl/config, just run:
aictl

# Or send a single message:
aictl --message "What is Rust?"

# Override provider/model from the command line:
aictl --provider openai --model gpt-4o --message "What is Rust?"

# Agent with tool calls (interactive confirmation)
aictl --message "List files in the current directory"

# Autonomous mode (no confirmation prompts)
aictl --auto --message "What OS am I running?"

# Quiet mode (only final answer, no tool calls or reasoning)
aictl --auto --quiet --message "What OS am I running?"

# JSON envelope on stdout (for scripting; tool/reasoning chatter dropped)
aictl --format json --message "What is Rust?"

# Plain prose with markdown stripped
aictl --format text --message "Explain Rust ownership"

Tests

cargo test

Unit tests cover core logic across six modules: commands (slash command parsing), config (config file parsing), tools (tool-call XML parsing), ui (formatting helpers), llm (cost estimation and model matching), and security (shell validation, path validation, output sanitization). The session module handles persistence of REPL conversations under ~/.aictl/sessions/.

Roadmap

See ROADMAP.md for planned features and future direction, including new tools, UX improvements, desktop app plans, and coding agent capabilities.

Architecture

See ARCH.md for detailed ASCII diagrams covering:

• Module structure
• Startup flow
• Agent loop
• Tool execution dispatch
• LLM provider abstraction
• UI layer
• End-to-end data flow

Claude Code Skills

This project includes Claude Code skills for common workflows. Run them as slash commands in a Claude Code session:

Evaluation reports are saved to .claude/reports/ with timestamped filenames.

License

This project is licensed under the PolyForm Noncommercial License 1.0.0. It is free to use for non-commercial purposes, including personal use, research, education, and use by non-profit organizations. For commercial use, please contact [email protected].