agentic-cli

agentic-cli is a model-provider-agnostic agentic CLI. Give it a natural-language task and it can plan, gather context, inspect and edit files, run safe commands, and optionally work with Git and GitHub — from your terminal.

It is not locked to one model provider. It talks to any OpenAI-compatible chat completions endpoint, including:

• OpenAI
• Ollama (local)
• LM Studio (local)
• Custom OpenAI-compatible endpoints (vLLM, llama.cpp server, etc.)
• Groq, Mistral, Together, OpenRouter, and GitHub Models (same protocol, built-in defaults)
• Gemini, DeepSeek, and xAI (OpenAI-compatible endpoints)
• Anthropic (native Messages API with tool calling and streaming)

Features

• Provider abstraction layer — the agent loop never knows which provider it is talking to
• ask, plan, run, review, doctor, init, config, logs
• mock-server: a built-in fake OpenAI-compatible server for testing/demos
• Interactive chat mode: agentic-cli chat
• Plan-first agent runs: agentic-cli run --plan-first
• --json output for doctor, ask, run, and logs
• Interactive setup wizard: agentic-cli init --interactive
• Shell completion: agentic-cli --install-completion
• Native tool calling when available, prompt-based JSON tool calls otherwise
• Streaming, JSON mode, timeouts, retries with exponential backoff
• Dry-run by default for agent runs; --apply / --yes opt into changes
• Allow/deny lists for shell commands; destructive commands require confirmation
• Force-push is always disabled; creating pull requests is preferred over pushing to base
• ask_user and web_fetch tools; schema-validated tool arguments
• Parallel read-only tool execution and in-run tool caching
• Hard budgets: max steps, max tool calls, max runtime, max context tokens
• Hierarchical sub-agents: delegate_task with sub-sub-agent support
• benchmark command for latency, throughput, and startup measurements
• MCP support: stdio, HTTP, and SSE servers expose their tools to the agent
• Resumable sessions: run --resume <session-id> and chat --session <id>
• Repository guidance: AGENTS.md / CLAUDE.md auto-loaded into the prompt
• Model fallback routing: model.fallbacks fail over to backup endpoints
• Sandbox command profiles: --sandbox safe|readonly|default|none
• Fast startup: prebuilt binaries launch in ~150 ms (onedir bundles)
• Secrets are never stored, printed, or logged
• Optional GitHub integration driven by GITHUB_TOKEN
• Works on Windows (PowerShell, Command Prompt, WSL), macOS, and Linux

Requirements

• Node.js 18+ (required for the one-command npm install)
• Python 3.10+ (only for source/pip installs and the npm Python fallback)
• A model endpoint (local or hosted)

Installation

The CLI binary is agentic-cli no matter which method you use. All methods below were tested from a clean environment.

1. One command, no Python needed (recommended)

On Windows x64, macOS (Intel and Apple Silicon), and Linux x64/ARM64, the npm package downloads a prebuilt standalone binary for your platform. No Python, no build tools, no setup:

# After publishing to the npm registry
npm install -g agentic-cli-oss

# Verify
agentic-cli --version

Or run it without installing:

npx agentic-cli --version

If the npm package ever needs its Python environment rebuilt (for example on an unsupported platform), it falls back automatically to an isolated Python install — see method 5.

2. From source (development)

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

2. Plain pip (any Python 3.10+)

pip install .

On Windows, if python is not on your PATH, use the launcher:

py -3.11 -m pip install .

3. pipx (recommended for end users)

pipx installs into an isolated environment and puts agentic-cli on your PATH:

python -m pip install --user pipx
python -m pipx ensurepath
pipx install .

4. uv (alternative isolated installer)

uv tool install .

5. npm with Python fallback (unsupported platforms / local installs)

The npm package prefers a prebuilt platform binary. If no binary matches your platform, postinstall creates an isolated Python environment inside the package and installs the wheel instead:

# From this repository
npm install -g .

# Or install locally in a project
npm install <path-to-this-repository>

After publishing to the npm registry (distribution name agentic-cli-oss):

npm install -g agentic-cli-oss
npx agentic-cli --version

If the Python fallback environment is missing or out of date:

npm rebuild agentic-cli-oss

6. Published Python package

Once published to PyPI (distribution name agentic-cli-oss, because the plain agentic-cli name is taken by an unrelated project):

pip install agentic-cli-oss

Verify the install

agentic-cli --version
agentic-cli --help
agentic-cli doctor

Troubleshooting

• command not found / not recognized: your user pip install location is not on PATH. Use pipx, activate a virtual environment, or add the Scripts/bin directory from python -m site --user-base to your PATH.
• npm install fails with a Python error: install Python 3.10+ first, or run npm rebuild agentic-cli-oss after installing it.
• agentic-cli doctor cannot connect: see the provider guides below; the command prints the exact endpoint it tried and what to start.

Releasing new versions

The release pipeline is ready in .github/workflows/ci.yml: pushing a vX.Y.Z tag builds standalone binaries for Windows x64, macOS x64/ARM64, and Linux x64, publishes each platform package, and publishes the root npm package (requires an NPM_TOKEN secret). Locally, a single platform can be built with:

npm run build:binary
npm publish platform-packages/agentic-cli-oss-<your-platform>

To publish everything from your machine in one command:

npm login                 # one-time npm account authorization
npm run publish:all       # builds nothing; publishes platform binaries + root

publish:all checks that you are logged in, verifies every platform package version matches the root version, publishes the platform packages that have a built binary on this machine, and finally publishes agentic-cli-oss. It skips platforms without a binary (for example darwin-x64 on a non-Intel machine) and tells you how to publish those later. prepack automatically strips __pycache__/.pyc files from the published source tree.

Note: GitHub's hosted runners no longer provide Intel macOS machines, so the darwin-x64 binary is built by maintainers on an Intel Mac (or the CI build-binaries matrix can be extended when a suitable runner is available). All other platform binaries are built automatically.

Quick start

Ollama

Start Ollama, then:

agentic-cli init --provider ollama --model llama3.1
agentic-cli doctor
agentic-cli ask "Explain this repository"

Defaults: http://localhost:11434/v1, no API key required.

LM Studio

Enable the local server in LM Studio (Settings > Developer > Start Server), then:

agentic-cli init --provider lmstudio --model local-model
agentic-cli doctor
agentic-cli ask "Explain this repository"

Defaults: http://localhost:1234/v1, no API key required.

OpenAI

export OPENAI_API_KEY=your_api_key_here     # Windows: set OPENAI_API_KEY=...
agentic-cli init --provider openai --model gpt-4o-mini
agentic-cli ask "Explain this repository"

Custom OpenAI-compatible endpoint

agentic-cli init --provider openai-compatible \
  --base-url http://localhost:8000/v1 \
  --model my-model

# With an API key held in a custom environment variable
agentic-cli init --provider openai-compatible \
  --base-url https://api.example.com/v1 \
  --model my-model \
  --api-key-env MY_CUSTOM_API_KEY
export MY_CUSTOM_API_KEY=your_api_key_here

CLI reference

agentic-cli --version                     Show version
agentic-cli init                          Create a local config file
agentic-cli doctor                        Check config, API key, and connectivity
agentic-cli ask "..."                     One-shot question
agentic-cli chat                          Interactive chat session
agentic-cli plan "..."                    Generate a plan, make no changes
agentic-cli run "..."                     Agentic task loop (dry-run by default)
agentic-cli run "..." --plan-first        Generate a plan, then execute
agentic-cli run "..." --max-subagent-depth 3
agentic-cli run "..." --apply             Apply changes
agentic-cli run "..." --apply --yes       Apply changes without confirmation prompts
agentic-cli run "..." --resume <id>       Continue a previous session
agentic-cli run "..." --sandbox safe      Restrict shell commands
agentic-cli review                        Review branch diff vs base branch
agentic-cli review --diff                 Review working-tree diff
agentic-cli review --pr 42                Review a GitHub pull request
agentic-cli config                        Show effective configuration (no secrets)
agentic-cli config model.provider ollama  Set a config value
agentic-cli logs                          List previous runs
agentic-cli logs --run-id <id>            Show one run's tool actions
agentic-cli sessions list                 List resumable sessions
agentic-cli sessions show --id <id>       Show a session's messages
agentic-cli sessions delete --id <id>     Delete a session
agentic-cli mcp list                      List configured MCP servers
agentic-cli mcp check                     Connect to MCP servers and list tools
agentic-cli mock-server --port 18080      Start a fake OpenAI-compatible server
agentic-cli benchmark --requests 10       Measure latency, memory, throughput

Common model flags on every model-facing command:

--provider <name>      openai | openai-compatible | ollama | lmstudio | groq | mistral | together | openrouter | github-models
--model <name>         Model identifier
--base-url <url>       OpenAI-compatible base URL

Run-specific flags:

--dry-run / --apply    Force dry-run or apply mode
--yes                  Skip confirmation prompts
--allow <prefix>       Allow a shell command prefix (repeatable)
--deny <prefix>        Deny a shell command prefix (repeatable)
--max-steps <n>        Override the maximum agent steps
--max-tool-calls <n>   Override the maximum tool calls per run
--max-runtime <s>      Override the maximum run duration in seconds
--resume <session>     Continue a previous run session
--sandbox <profile>    none, default, safe, or readonly

Machine-readable output:

agentic-cli doctor --json                 Diagnostics as JSON
agentic-cli ask "..." --json              Response as JSON
agentic-cli run "..." --json              Run summary as JSON
agentic-cli logs --json                   Run history as JSON

Configuration

Priority order: CLI flags > environment variables > config file > defaults.

Environment variables

Generic model configuration:

| Variable | Meaning | | --- | --- | | MODEL_PROVIDER | Provider name (ollama, lmstudio, openai, ...) | | MODEL_NAME | Model identifier | | MODEL_BASE_URL | OpenAI-compatible base URL | | MODEL_API_KEY | API key (preferred over provider-specific keys) | | MODEL_API_VERSION | Optional API version header | | MODEL_TIMEOUT | Request timeout in seconds | | MODEL_MAX_TOKENS | Max completion tokens | | MODEL_TEMPERATURE | Sampling temperature |

Provider API keys:

| Variable | Used for | | --- | --- | | OPENAI_API_KEY | OpenAI | | ANTHROPIC_API_KEY | Anthropic | | GROQ_API_KEY | Groq | | MISTRAL_API_KEY | Mistral | | TOGETHER_API_KEY | Together | | OPENROUTER_API_KEY | OpenRouter | | GITHUB_TOKEN | GitHub Models and GitHub API | | GOOGLE_API_KEY | Gemini | | DEEPSEEK_API_KEY | DeepSeek | | XAI_API_KEY | xAI (Grok) |

GitHub:

| Variable | Meaning | | --- | --- | | GITHUB_TOKEN | GitHub API token | | GITHUB_OWNER | Repository owner | | GITHUB_REPO | Repository name | | GITHUB_BASE_BRANCH | Base branch (default main) |

Agent behavior:

| Variable | Meaning | | --- | --- | | AGENTIC_CLI_MAX_STEPS | Max agent steps | | AGENTIC_CLI_MAX_TOOL_CALLS | Max tool calls per run | | AGENTIC_CLI_MAX_RUNTIME_SECONDS | Max run duration in seconds | | AGENTIC_CLI_MAX_SUBAGENT_DEPTH | Max sub-agent nesting depth (default 3) | | AGENTIC_CLI_MAX_SUBAGENTS | Max total sub-agent delegations per run (default 8) | | AGENTIC_CLI_DRY_RUN_BY_DEFAULT | true/false | | AGENTIC_CLI_REQUIRE_CONFIRMATION | true/false | | AGENTIC_CLI_ALLOWED_COMMANDS | JSON list or comma-separated command prefixes | | AGENTIC_CLI_DENIED_COMMANDS | JSON list or comma-separated command prefixes | | AGENTIC_CLI_MAX_COMMAND_TIMEOUT | Max seconds per shell command | | AGENTIC_CLI_MAX_CONTEXT_TOKENS | Rough context limit for the agent loop | | AGENTIC_CLI_SANDBOX | Sandbox profile: none, default, safe, readonly | | AGENTIC_CLI_LOG_LEVEL | Log level | | AGENTIC_CLI_CONFIG | Path to a config file | | AGENTIC_CLI_LOG_DIR | Directory for run logs | | AGENTIC_CLI_SESSION_DIR | Directory for resumable sessions |

Config file

The CLI looks for, in order:

1. .agentic-cli.json (project)
2. agentic-cli.config.json (project)
3. ~/.config/agentic-cli/config.json (user)

Or any path in AGENTIC_CLI_CONFIG.

Secrets are never stored in the config file — only the name of the environment variable that contains the secret:

{
  "model": {
    "provider": "ollama",
    "name": "llama3.1",
    "baseUrl": "http://localhost:11434/v1",
    "apiKeyEnvVar": null,
    "fallbacks": [
      {
        "provider": "openai-compatible",
        "name": "backup-model",
        "baseUrl": "http://localhost:8000/v1"
      }
    ]
  },
  "agent": {
    "maxSteps": 20,
    "dryRunByDefault": true,
    "requireConfirmation": true,
    "sandbox": "default",
    "repoGuidance": ["AGENTS.md", "CLAUDE.md"]
  },
  "mcp": {
    "servers": [
      {
        "name": "filesystem",
        "transport": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
      }
    ]
  },
  "github": {
    "owner": "your-github-username",
    "repo": "your-github-username/your-repo-name",
    "baseBranch": "main",
    "tokenEnvVar": "GITHUB_TOKEN"
  }
}

See agentic-cli.example.json for the full schema.

Provider guide

| Provider | Base URL default | API key | Tool calling | | --- | --- | --- | --- | | openai | https://api.openai.com/v1 | Required | Native | | openai-compatible | http://localhost:8000/v1 | Optional | Native/fallback | | ollama | http://localhost:11434/v1 | Optional | Native/fallback | | lmstudio | http://localhost:1234/v1 | Optional | Native/fallback | | groq | https://api.groq.com/openai/v1 | Required | Native | | mistral | https://api.mistral.ai/v1 | Required | Native | | together | https://api.together.xyz/v1 | Required | Native | | openrouter | https://openrouter.ai/api/v1 | Required | Native | | github-models | https://models.github.ai/inference/v1 | Required | Native | | gemini | https://generativelanguage.googleapis.com/v1beta/openai | Required | Native | | deepseek | https://api.deepseek.com/v1 | Required | Native | | xai | https://api.x.ai/v1 | Required | Native | | anthropic | https://api.anthropic.com/v1 | Required | Native (Messages API) |

Ollama

1. Install and start Ollama: https://ollama.com
2. Pull a model: ollama pull llama3.1
3. Configure:

agentic-cli init --provider ollama --model llama3.1

The OpenAI-compatible endpoint is http://localhost:11434/v1. No API key is required. If your setup requires a placeholder key, set MODEL_API_KEY=ollama. If the server is unreachable, agentic-cli doctor explains exactly that.

LM Studio

1. Open LM Studio, load a model, and start the local server (Settings > Developer > Start Server).
2. Configure:

agentic-cli init --provider lmstudio --model local-model

The OpenAI-compatible endpoint is http://localhost:1234/v1. No API key is required. If your setup requires a placeholder key, set MODEL_API_KEY=lm-studio.

OpenAI

export OPENAI_API_KEY=your_api_key_here
agentic-cli init --provider openai --model gpt-4o-mini

OpenAI-compatible endpoints

Any server exposing POST {base_url}/chat/completions works:

agentic-cli init --provider openai-compatible \
  --base-url http://localhost:8000/v1 \
  --model my-model

If the endpoint requires a key, either set OPENAI_API_KEY, MODEL_API_KEY, or point the config at a custom environment variable with --api-key-env.

Other providers (Groq, Mistral, Together, OpenRouter, GitHub Models)

These use the same OpenAI-compatible protocol with built-in defaults:

export GROQ_API_KEY=your_api_key_here
agentic-cli init --provider groq --model llama-3.3-70b-versatile

GitHub Models uses GITHUB_TOKEN:

export GITHUB_TOKEN=github_pat_your_token_here
agentic-cli init --provider github-models --model gpt-4o-mini

Anthropic

The Anthropic adapter implements the native Messages API, including tool calling and streaming:

export ANTHROPIC_API_KEY=your_api_key_here
agentic-cli init --provider anthropic --model claude-sonnet-4-5
agentic-cli ask "Explain this repository"

Gemini, DeepSeek, xAI

These providers use OpenAI-compatible endpoints:

export GOOGLE_API_KEY=your_api_key_here
agentic-cli init --provider gemini --model gemini-2.5-flash

export DEEPSEEK_API_KEY=your_api_key_here
agentic-cli init --provider deepseek --model deepseek-chat

export XAI_API_KEY=your_api_key_here
agentic-cli init --provider xai --model grok-3-mini

Mock server

For testing, demos, and CI without a real model endpoint:

agentic-cli mock-server --port 18080 --model fake-model

Then point any command at it:

agentic-cli doctor --provider openai-compatible --base-url http://127.0.0.1:18080/v1 --model fake-model
agentic-cli ask "Hello" --provider openai-compatible --base-url http://127.0.0.1:18080/v1 --model fake-model

The server implements GET /v1/models and POST /v1/chat/completions (plain and streaming) and echoes the last user message.

API key setup

Never type a real key into a command line argument and never put one in a config file. Use environment variables:

# Generic key (works with any provider)
export MODEL_API_KEY=your_api_key_here

# Provider-specific
export OPENAI_API_KEY=your_api_key_here
export GROQ_API_KEY=your_api_key_here

# Config referencing a custom variable
agentic-cli init --provider openai-compatible --api-key-env MY_CUSTOM_API_KEY
export MY_CUSTOM_API_KEY=your_api_key_here

Key resolution order for the active provider:

1. The environment variable named by model.apiKeyEnvVar in config
2. MODEL_API_KEY
3. The provider-specific variable (OPENAI_API_KEY, GROQ_API_KEY, ...)

Local providers (Ollama, LM Studio) do not require a key. If their endpoint does, a placeholder such as ollama or lm-studio is sufficient.

GitHub token setup

GitHub tools (review --pr, github_* tools, pushes, PRs) need a token:

1. Create a fine-grained personal access token at https://github.com/settings/personal-access-tokens (or a classic token).
2. Grant repository read/write permissions for the repositories you use.
3. Export it:

export GITHUB_TOKEN=github_pat_your_token_here

If GITHUB_OWNER and GITHUB_REPO are unset, agentic-cli infers them from the origin remote. If it cannot, it fails with a clear message.

Windows setup

PowerShell — current session

$env:MODEL_PROVIDER = "ollama"
$env:MODEL_NAME = "llama3.1"
$env:MODEL_BASE_URL = "http://localhost:11434/v1"
$env:GITHUB_OWNER = "your-github-username"
$env:GITHUB_REPO = "your-github-username/your-repo-name"
$env:GITHUB_BASE_BRANCH = "main"

PowerShell — permanent user variables

[Environment]::SetEnvironmentVariable("MODEL_PROVIDER", "ollama", "User")
[Environment]::SetEnvironmentVariable("MODEL_NAME", "llama3.1", "User")
[Environment]::SetEnvironmentVariable("MODEL_BASE_URL", "http://localhost:11434/v1", "User")
[Environment]::SetEnvironmentVariable("GITHUB_OWNER", "your-github-username", "User")
[Environment]::SetEnvironmentVariable("GITHUB_REPO", "your-github-username/your-repo-name", "User")
[Environment]::SetEnvironmentVariable("GITHUB_BASE_BRANCH", "main", "User")

Command Prompt — current session

set MODEL_PROVIDER=ollama
set MODEL_NAME=llama3.1
set MODEL_BASE_URL=http://localhost:11434/v1
set GITHUB_OWNER=your-github-username
set GITHUB_REPO=your-github-username/your-repo-name
set GITHUB_BASE_BRANCH=main

Command Prompt — permanent user variables

setx MODEL_PROVIDER "ollama"
setx MODEL_NAME "llama3.1"
setx MODEL_BASE_URL "http://localhost:11434/v1"
setx GITHUB_OWNER "your-github-username"
setx GITHUB_REPO "your-github-username/your-repo-name"
setx GITHUB_BASE_BRANCH "main"

Security warning: do not permanently store API keys or GitHub tokens with setx or [Environment]::SetEnvironmentVariable unless you understand the risk. They are stored in plain text in the user registry/environment. Prefer session-scoped variables, or use Windows Credential Manager with a wrapper.

WSL

export MODEL_PROVIDER=ollama
export MODEL_NAME=llama3.1
export MODEL_BASE_URL=http://localhost:11434/v1
export GITHUB_OWNER=your-github-username
export GITHUB_REPO=your-github-username/your-repo-name
export GITHUB_BASE_BRANCH=main

If Ollama runs on Windows, use http://host.docker.internal:11434/v1 (Docker WSL2) or your Windows host IP, and make sure Ollama allows LAN connections.

macOS / Linux setup

export MODEL_PROVIDER=ollama
export MODEL_NAME=llama3.1
export MODEL_BASE_URL=http://localhost:11434/v1
export OPENAI_API_KEY=your_api_key_here
export GITHUB_TOKEN=github_pat_your_token_here

To make them permanent, add the exports to ~/.bashrc, ~/.zshrc, or ~/.profile. Again: prefer session-scoped variables for secrets.

Safety

• run defaults to dry-run: mutating tools are reported as planned actions and not executed.
• --apply executes mutations; --yes also skips confirmation prompts.
• Destructive shell commands (recursive deletes, resets, etc.) require confirmation even with --apply, unless --yes is passed.
• Shell commands are limited by timeouts and optional allow/deny prefixes.
• Sandbox profiles add extra guardrails: safe denies destructive commands outright; readonly only allows read-only commands.
• Force-push is always denied, even with --yes.
• The agent prefers creating pull requests over pushing to the base branch.
• Secrets are redacted from logs, tool output, errors, and history.

Sub-agents

For very large tasks the main agent can delegate well-scoped subtasks with the delegate_task tool. Sub-agents can delegate further — sub-sub-agents — up to agent.maxSubagentDepth (default 3). The parent monitors every delegated result, reviews it, and continues its own work; run summaries include each sub-agent's task, stop reason, steps, and token usage.

# Raise nesting depth and delegation count for the hardest tasks
agentic-cli run "Refactor the whole codebase" --apply --yes \
  --max-subagent-depth 4 --max-subagents 20

Delegation is bounded by maxSubagents (default 8 total per run), and every delegate runs with its own step/tool/runtime budgets. Parallel fan-out is supported by passing tasks and parallel: true to the tool.

Sessions and resume

Every run is saved to ~/.agentic-cli/sessions (or AGENTIC_CLI_SESSION_DIR): the task, configuration snapshot, assistant/tool messages, and final summary. That means an interrupted or long-running task can be continued on any machine:

# Run a task, then note the session id printed at the end
agentic-cli run "Refactor the CLI" --apply

# Continue that session later (even with a different provider/model)
agentic-cli run "finish the remaining cleanup" --resume 1a2b3c4d5e6f

# Inspect or remove sessions
agentic-cli sessions list
agentic-cli sessions show --id 1a2b3c4d5e6f
agentic-cli sessions delete --id 1a2b3c4d5e6f

Interactive chats are also resumable: agentic-cli chat --session <id>.

MCP servers

The Model Context Protocol lets you connect external tools (filesystem, GitHub, databases, browsers, custom services) without changing agentic-cli itself. Configure servers under mcp.servers in the config file:

{
  "mcp": {
    "servers": [
      {
        "name": "filesystem",
        "transport": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
      },
      {
        "name": "github",
        "transport": "http",
        "url": "http://localhost:8931/mcp",
        "headers": { "Authorization": "env:GITHUB_TOKEN" }
      }
    ]
  }
}

• stdio spawns a local process (e.g. npx ...).
• http and sse connect to remote MCP endpoints.
• env:VAR values in headers/env are resolved from your environment, so secrets never land in the config file.
• Each server's tools become mcp__<server>__<tool> for the agent.
• agentic-cli mcp list shows configured servers; agentic-cli mcp check connects and lists available tools; doctor includes MCP diagnostics.

Repository guidance

If a repository contains AGENTS.md or CLAUDE.md, agentic-cli finds it from the working directory up to the repo root and injects it into the system prompt, so the agent follows project conventions automatically. Configure which files to load with agent.repoGuidance:

{ "agent": { "repoGuidance": ["AGENTS.md", "GUIDE.md"] } }

Set it to false (or []) to disable.

Model fallbacks

When the primary model endpoint fails (connection, auth, or API error), agentic-cli automatically tries the next endpoint in model.fallbacks:

{
  "model": {
    "provider": "openai",
    "name": "gpt-4o-mini",
    "fallbacks": [
      { "provider": "ollama", "name": "llama3.1" },
      {
        "provider": "openai-compatible",
        "name": "backup-model",
        "baseUrl": "http://localhost:8000/v1"
      }
    ]
  }
}

Fallback endpoints use the same key-resolution rules as the primary provider (MODEL_API_KEY, provider-specific variables, or apiKeyEnvVar).

Sandbox profiles

agent.sandbox (or --sandbox / AGENTIC_CLI_SANDBOX) selects a shell-command profile:

| Profile | Behavior | | --- | --- | | default | Existing behavior: allow/deny lists, destructive confirmation, no force-push | | safe | Also denies destructive commands outright (recursive deletes, resets, --force pushes, disk formatting, etc.) | | readonly | Only read-only commands (git status, git diff, cat, ls, ...) | | none | No profile restrictions beyond built-in force-push protection |

agentic-cli run "Audit the repo" --sandbox readonly
agentic-cli run "Fix the build" --apply --sandbox safe

How this compares to Gemini CLI / Codex

agentic-cli is a model-provider-agnostic, open-source alternative in the same family as Google's Gemini CLI and OpenAI's Codex CLI. Shared capabilities: natural-language tasks, plan-first runs, tool calling, file/command/Git/GitHub workflows, sub-agents, dry-run safety, and JSON output.

What agentic-cli adds for flexibility:

• One abstraction over OpenAI, Ollama, LM Studio, Anthropic, Groq, Mistral, Together, OpenRouter, GitHub Models, Gemini, DeepSeek, and xAI, plus any OpenAI-compatible endpoint; model fallback routing when the primary fails.
• MCP client support (stdio/HTTP/SSE) with tools exposed to the agent.
• Resumable sessions, repository guidance (AGENTS.md), sandbox profiles, and a built-in benchmark with latency/memory/startup metrics.
• One-command npm install with optional prebuilt binaries and a pure-Python fallback, so the same install works on Windows, macOS, Linux, and WSL.
• Faster cold start than single-file binaries: onedir npm builds launch in ~150 ms, and --version needs no runtime extraction.

Differences to keep in mind: Gemini CLI and Codex ship first-party hosted toolchains (Gemini API, OpenAI Codex, Google account sync, stronger IDE-integrated UX), while agentic-cli is fully provider-agnostic and works offline against local models.

Example workflows

# Diagnose a failing test without touching anything
agentic-cli run "Investigate why tests fail and propose a fix" --max-steps 12

# Apply a fix
agentic-cli run "Fix the failing tests" --apply --yes

# Plan a feature
agentic-cli plan "Add a --json output flag to the CLI"

# Review local work
agentic-cli review
agentic-cli review --diff

# Review a pull request
export GITHUB_TOKEN=github_pat_your_token_here
agentic-cli review --pr 42

# Show what a run did
agentic-cli logs
agentic-cli logs --run-id 1a2b3c4d5e6f

# Continue an interrupted task
agentic-cli run "finish the remaining work" --resume 1a2b3c4d5e6f

# Connect external MCP tools and verify them
agentic-cli mcp list
agentic-cli mcp check

# Benchmark with memory and percentile latency
agentic-cli benchmark --requests 10 --stream --json

Architecture

src/agentic_cli/
├── cli.py            Typer CLI entrypoint
├── config.py         Config loading (flags > env > file > defaults)
├── models.py         Configuration data models
├── redaction.py      Secret redaction
├── logging_utils.py  Logging with redaction filter
├── doctor.py         Diagnostics
├── sessions.py       Resumable session storage
├── agent/
│   ├── loop.py       Agent loop (plan, act, observe, stop)
│   ├── planning.py   One-shot plan generation
│   ├── prompts.py    Prompt templates
│   ├── context.py    Repository context gathering
│   └── guidance.py   AGENTS.md / CLAUDE.md discovery
├── provider/
│   ├── base.py       Provider adapter interface
│   └── registry.py   All built-in provider adapters
├── client/
│   ├── chat.py       Chat client: retries, streaming, JSON mode, tool calls
│   ├── factory.py    Client construction
│   └── fallback.py   Model fallback routing
├── mcp/
│   ├── client.py     MCP stdio/HTTP/SSE JSON-RPC clients
│   └── tools.py      MCP tools exposed to the agent
├── tools/            Modular tool system (filesystem, shell, git, github)
├── git/utils.py      Git subprocess wrappers
├── github_client.py  GitHub REST client
└── history/store.py  JSONL run history

The agent loop only talks to the ProviderAdapter interface and the ToolRegistry; adding a provider or tool never rewrites the loop.

Testing and linting

pip install -e ".[dev]"
ruff check src tests
ruff format --check src tests
pytest

Tests use httpx.MockTransport, fakes, and monkeypatching. They never require real API keys, GitHub tokens, or running local model servers.

Contributing

See CONTRIBUTING.md.

License

MIT — see LICENSE.