Documentation

Overview

Cipher is an open-source, terminal-based autonomous coding agent. You describe a task in natural language — Cipher reads your codebase, writes files, runs commands, searches the web, and reports back when done.

It runs entirely in your terminal as a rich TUI (terminal user interface) with a persistent chat sidebar, live tool output display, and session history. No browser, no IDE extension, no cloud dashboard required.

Key characteristics

• Free to use — The built-in Cipher Proxy provides Gemini and Llama models at no cost, no API key needed.
• Bring your own model — Connect to any of 14+ providers using your own API keys.
• Local AI support — Works with Ollama and LM Studio for fully offline, private operation.
• Two-agent architecture — Separate Chat AI (reasoning) and Coding AI (execution) for better results and efficiency.
• Full tool suite — File read/write/edit, shell execution, web fetch, web search, git, grep, glob, and more.
• Cross-platform — Mac, Linux, and Windows (PowerShell) fully supported.
• Persistent sessions — All conversations saved with AI-generated titles, resumable at any time.

Installation

Install Cipher using any of the methods below. All methods install the same package and create cipher and cip commands in your PATH.

pip (recommended)

pip install cipher-agent --upgrade

Requires Python 3.9 or later. The --upgrade flag ensures you get the latest version if already installed.

npm

npm install -g cipher-agent

Requires Node.js 14+. The npm wrapper automatically locates and runs the Python package.

Windows (one-line installer)

# Run in PowerShell as Administrator
irm https://cipher.elevenpct.com/install.ps1 | iex

Mac / Linux (one-line installer)

curl -fsSL https://cipher.elevenpct.com/install.sh | bash

Install from source

git clone https://github.com/elevenpercent/cipher
cd cipher
pip install -e .

The -e flag installs in editable mode so local changes take effect immediately.

Quick start

After installing, navigate to your project directory and launch Cipher:

cd ~/my-project
cipher
# or the short alias:
cip

The first time you run Cipher, it opens the setup screen where you choose a provider. Select Cipher Proxy to get started immediately with no API key.

Once inside, type any coding task and press Enter:

> build a Flask REST API with JWT authentication
> add unit tests to my payment module
> refactor auth.py to use async functions
> what does the DatabaseManager class do?

Cipher will plan the task, use tools to execute it, and report back. You can ask follow-up questions, request changes, or start a new task.

Provider setup

The setup screen appears on first launch (or via /settings). It shows all available providers. Select one and press Enter to configure it.

Cipher Proxy Free

The easiest way to use Cipher. No API key, no account, no configuration. Cipher Proxy is a serverless proxy that routes requests to Gemini 2.0 Flash and Llama 3.3 70B models — free of charge.

Select Cipher Proxy in the setup screen and you're done. The app will show Cipher AI in the interface to reflect that you're using the managed proxy.

OpenAI API key

Provider: openai
Model:    gpt-4o
API Key:  sk-...

Anthropic API key

Provider: anthropic
Model:    claude-3-5-sonnet-20241022
API Key:  sk-ant-...

Google Gemini API key

Provider: gemini
Model:    gemini-2.0-flash
API Key:  AIza...

Ollama Local

Provider: ollama
Model:    llama3.2
# Make sure Ollama is running: ollama serve

LM Studio Local

Provider: lm-studio
Model:    your-model-name
# LM Studio must be running with the local server enabled

Interface

Cipher's TUI is divided into two main areas:

Left sidebar

• Session list — all saved sessions for the current project, with AI-generated titles. Click or navigate to resume any session.
• Provider info — shows the active provider name and model at the bottom of the sidebar.
• New session — press Ctrl+N or select the + button to start a new session.

Main chat area

• Messages — your messages and Cipher's responses appear in a scrollable view.
• Tool output — when Cipher uses a tool (write, run, edit, etc.), the result appears as an expandable card. Click to expand and see the full content.
• Streaming — AI responses stream in real-time. You can see Cipher thinking and writing as it happens.
• Input — the text input is at the bottom. Press Enter to send, Shift+Enter for a newline.

Header

Shows the current provider/model on the right and the project path on the left. The header updates immediately when you switch providers.

Keyboard shortcuts

Slash commands

Type a slash command in the input box and press Enter to execute it. Slash commands interact with Cipher directly and don't go to the AI.

Sessions

Every conversation with Cipher is a session. Sessions are automatically saved to ~/.cipher/sessions/ and persist between launches.

Session titles

When you start a task, Cipher automatically generates a descriptive title for the session based on the task you gave it. The title comes from the AI's own understanding of the task — not just a truncation of your input. This makes it easy to find and resume past sessions.

Resuming a session

Navigate the session list in the left sidebar using arrow keys or by clicking. Selecting a session restores its full message history and context. You can continue any past session exactly where you left off.

Session storage

Sessions are stored as JSON files in ~/.cipher/sessions/. Each file contains the session ID, title, timestamp, and full message history. You can inspect, back up, or delete them directly.

Providers

Cipher supports 14+ AI providers. Switch between them at any time using /settings.

Setting an API key

You can set API keys in two ways:

• In the settings screen — Enter the key directly when selecting a provider. It's saved to ~/.cipher/config.json.
• Via environment variable — Set the appropriate env var before launching (e.g. export OPENAI_API_KEY=sk-...). Environment variables take precedence over the config file.

Configuration

Cipher stores its configuration in ~/.cipher/config.json. This file is created automatically when you configure a provider. You can edit it directly.

{
  "provider": "cipher-proxy",
  "model": "llama-3.3-70b",
  "api_key": "",
  "base_url": ""
}

CLI reference

Cipher is invoked from the terminal. Both cipher and cip point to the same binary.

cipher [directory] [-p prompt] [-h]

Examples

# Open Cipher in the current directory
cipher

# Open a specific project
cipher ~/my-project

# Start with a task (skips the input box, immediately sends the prompt)
cipher -p "add error handling to all API endpoints"

# Short alias
cip

Tools reference

The Coding AI communicates using XML-style tool tags. Each tool has a specific syntax. Understanding these tags helps you understand what Cipher is doing and how to describe tasks that use specific tools.

File tools

Search tools

Execution tools

Web tools

Task management

Two-agent system

Cipher uses two specialized AI agents that work together on every task. Understanding how they work helps you write better prompts and understand what you see in the interface.

Phase 1 — Chat AI

When you send a message, it first goes to the Chat AI (Gemini 2.0 Flash when using Cipher Proxy). The Chat AI:

• Understands the intent of your request
• Maintains the conversation history and context
• Decides whether to answer directly or delegate to the Coding AI
• For coding tasks, emits a <task> tag with a clear, specific instruction for the Coding AI
• Can ask clarifying questions if the request is ambiguous

Phase 2 — Coding AI

If the Chat AI emitted a <task>, the Coding AI (Llama 3.3 70B when using Cipher Proxy) takes over. The Coding AI:

• Receives the specific task from the Chat AI
• Has access to the full tool suite (read, write, edit, run, search, etc.)
• Works autonomously through a loop: reads files, writes code, runs tests, checks output, fixes errors
• Emits <done> when the task is finished, with a summary of what was done
• Can request error recovery via <fix> tags if it encounters a problem it can't resolve

Phase 3 — Summary

After the Coding AI finishes, the Chat AI receives the summary and responds to you in natural language — explaining what was done, noting any caveats, and asking if you'd like anything else.

Why two agents?

• Efficiency — The Chat AI (fast, small) handles most conversation turns. The Coding AI (powerful, large) only runs when there's actual work to do.
• Rate limit management — Using two different models means each model's rate limit is only used for its specific role, reducing rate limit errors by roughly 2/3.
• Better results — Each model is optimized for its task. The Chat AI is tuned for reasoning and conversation; the Coding AI is tuned for code generation and tool use.
• Clear separation — The conversation layer stays clean while the execution layer gets as deep as it needs to.

Smart model routing (Cipher Proxy)

When using Cipher Proxy, model selection is automatic:

Cipher Proxy

Cipher Proxy is a free, serverless proxy hosted on Vercel that gives you access to powerful AI models without needing your own API keys.

What it provides

• Gemini 2.0 Flash — Google's fast, capable model (via Google AI). 60 requests/minute on the free tier.
• Llama 3.3 70B — Meta's best open model, hosted on Groq's ultra-fast inference. 30 requests/minute on the free tier.
• Llama 3.1 8B — A smaller, faster Llama model for lightweight tasks. 30 requests/minute on the free tier.

Rate limits

Cipher Proxy uses the free tiers of Google AI and Groq. Rate limits are shared across all Cipher Proxy users. When a rate limit is hit, Cipher automatically retries with exponential backoff (5s → 15s → 30s). You'll see a "Rate limited, retrying..." message when this happens.

Privacy

Messages sent through Cipher Proxy pass through the Vercel serverless function to the respective AI provider. The proxy does not log or store messages. For sensitive codebases, use your own API keys or a local model via Ollama or LM Studio.

Troubleshooting

Cipher command not found

After installing with pip, the cipher command should be in your PATH. If not:

• On Mac/Linux: Add ~/.local/bin to your PATH: export PATH="$HOME/.local/bin:$PATH"
• On Windows: Check %APPDATA%\Python\Python3xx\Scripts is in your PATH, or use the PowerShell installer which handles this automatically.

Rate limit errors

You'll see this when the AI provider's free tier is temporarily exhausted. Cipher will retry automatically. If it persists:

• Wait a minute and try again
• Use /settings to switch to a different provider
• Get your own API key for Groq (free tier at console.groq.com) or Gemini (free tier at aistudio.google.com)

Commands not running on Windows

Cipher uses PowerShell for all <run> commands on Windows. If a command fails:

• Cipher automatically converts && to ; for command chaining
• To open files: tell Cipher to use Start-Process 'filename'
• Most common commands (python, pip, npm, node, git) work exactly the same in PowerShell

Ollama / LM Studio connection failed

• For Ollama: make sure the daemon is running (ollama serve) and the model is pulled (ollama pull llama3.2)
• For LM Studio: enable the local server in LM Studio's settings and ensure the model is loaded
• The default base URL for Ollama is http://localhost:11434 and LM Studio is http://localhost:1234

Slow responses

Response speed depends on the model and provider:

• Groq and Gemini Flash are the fastest options in Cipher Proxy
• Large local models (via Ollama/LM Studio) depend on your hardware
• If using your own API key and still slow, try a smaller/faster model variant

Uninstall

Cipher stores session data in ~/.cipher/. Remove this folder along with the package to fully uninstall.

Via pip

pip uninstall cipher-agent

Via npm

npm uninstall -g cipher-agent

Remove session data

# Mac / Linux
rm -rf ~/.cipher

# Windows PowerShell
Remove-Item -Recurse -Force $HOME\.cipher