Quick Start

Get Acorn running in under a minute.

1. Install from PyPI

pip install acorn-agent

2. Run it

acorn

On first launch Acorn walks you through authentication — pick a Gemini API key or a GCP project, and it saves your choice to ~/.acorn/config.json.

3. Or set a key up front (optional)

export GEMINI_API_KEY="your-key-here"

Get a free key at aistudio.google.com/apikey.

Installation

Acorn needs Python 3.11+ and either a Gemini API key or a GCP project with Vertex AI.

Prerequisites

  • Python 3.11 or higher
  • A Gemini API key (free at aistudio.google.com) or a GCP project with Vertex AI enabled

Install

pip install acorn-agent

Verify

acorn --version
# acorn 2.3.1

Upgrade

pip install --upgrade acorn-agent

Acorn checks for new releases on startup and tells you when one is available.

Configuration

Two optional files in your project root: .acorn.toml for settings and .acorn.md for instructions.

.acorn.toml — settings

Every section is optional; anything you leave out keeps its default.

.acorn.toml
[model]
pro = "gemini-3.1-pro-preview"
flash = "gemini-3-flash-preview"
temperature = 0.2
max_output_tokens = 8192

[routing]
enabled = true       # smart Flash/Pro selection
threshold = 200      # chars below which a request leans Flash
classifier = true    # ask the model to break ambiguous ties

[shell]
persistent = true    # share cd/exports/venv across commands

[web]
enabled = true       # web search and page fetching

[mcp]
enabled = true       # start configured MCP servers

[project]
gcp_project = "your-project-id"
location = "global"

[permissions]
safe_commands = [
    "npm run", "npm test", "cargo build",
    "python -m pytest", "make",
]

.acorn.md — project instructions

Persistent context injected into the system prompt, so Acorn follows your conventions without being reminded each session.

.acorn.md
# Project: MyApp

## Tech Stack
- Python 3.12, FastAPI, SQLAlchemy
- Frontend: React + TypeScript

## Conventions
- snake_case for Python, camelCase for TypeScript
- Always add type hints
- Tests go in tests/ with pytest

## Important
- Never modify migrations directly — use alembic
- The auth module is being rewritten, don't touch auth/legacy/

Environment variables

GEMINI_API_KEYGemini API key — the simplest setup
ACORN_PROJECTGCP project ID for Vertex AI mode
GCP_PROJECTAlternative GCP project variable
GOOGLE_CLOUD_PROJECTAlternative GCP project variable

Usage

Run acorn in any project directory to start an interactive session. Flags tune a single run; .acorn.toml makes the same changes permanent.

Model and auth

acorn --model <name>      # override the Pro model
acorn --flash <name>      # override the Flash model
acorn --project <id>      # override the GCP project ID
acorn --key <key>         # use a Gemini API key for this run
acorn --models            # list available models

Turning things off

acorn --no-shell     # one process per command, no shared state
acorn --no-web       # disable web search and page fetching
acorn --no-mcp       # don't start configured MCP servers
acorn --no-routing   # always use Pro
acorn --no-stream    # wait for the full response
acorn --no-session   # don't persist this conversation
acorn --unsafe       # auto-approve everything (dangerous)

Info

acorn --version   # or -v
acorn --help      # or -h

Sessions are automatic. Conversations save to ~/.acorn/sessions/ as you go — there's no flag to name one. Use /sessions inside a session to list them, or --no-session to skip saving entirely.

Commands

Slash commands work inside a running session.

CommandWhat it does
/helpShow all commands
/model <name>Switch model, or list available ones
/costSession cost breakdown
/statusToken usage, routing stats, cost
/planShow the current task execution plan
/routingExplain why the last request went to Flash or Pro
/routing on|offToggle smart routing
/shellShow shell mode and working directory
/shell resetClear shell state (cd, exports, venv)
/web on|offToggle web search and page fetching
/mcpList MCP servers and the tools they expose
/undoRevert the last file change
/sessionsList saved sessions
/configShow current configuration
/clearReset context and session
/exitQuit (or /quit)

Features

What Acorn brings to a session, all on by default.

Persistent shell

Commands run in one long-lived session, so cd, exported variables, and an activated virtualenv all carry across calls. A command that times out is interrupted on its own — the session and its state survive.

Web search built in

Searches the web and reads pages when it hits an unfamiliar library version, changelog, or error. No API key, no signup — it works on a fresh install.

MCP support

Speaks the Model Context Protocol, so any MCP server's tools become available to the agent. Servers start in parallel and one that fails never blocks startup.

Smart model routing

Scores each request on size, scope, and intent to pick Flash or Pro, with the model breaking genuinely ambiguous ties. Cuts cost substantially versus running Pro for everything.

Colored diffs

Every file change is shown as a real diff with line numbers, not a wall of replacement text.

Surgical file editing

Modifies specific lines rather than rewriting whole files — precise, and far less likely to clobber something.

Streaming responses

Tokens render as they arrive, with markdown formatted live rather than after the fact.

Session persistence

Conversations are saved to ~/.acorn/sessions/ so you can pick one back up later.

Undo

/undo reverts the last file change instantly.

Image analysis

Attach screenshots or images and the model reads them alongside your code.

Cost tracking

Per-session token usage and spend, visible at any time with /cost.

Git-aware

Understands your branch, working-tree status, and project structure without being told.

MCP Servers

Acorn uses the same config format as other MCP clients, so existing files work unchanged.

Where config lives

Acorn checks these in order and uses the first it finds:

  1. .mcp.json in the project root
  2. .acorn/mcp.json in the project root
  3. ~/.acorn/mcp.json for servers you want everywhere

Example

~/.acorn/mcp.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@mcp/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_..."
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@mcp/server-postgres", "postgresql://localhost/mydb"]
    }
  }
}

Run /mcp in a session to see which servers connected and what tools they exposed. Start Acorn with --no-mcp to skip them for one run.

Safety

Every action falls into one of three tiers before it runs.

Safe

Reads, searches, and allow-listed commands run without interrupting you. Extend the list with permissions.safe_commands in .acorn.toml.

Ask

File writes and unrecognised commands stop and wait for your confirmation, showing exactly what will change.

Deny

Destructive commands like rm -rf / are blocked outright and cannot be approved interactively.

--unsafe auto-approves every action, including file writes and arbitrary commands. Only use it in a throwaway container or a directory you're willing to lose.

How It Works

What happens between your message and the answer.

1

You send a message

Plain language — describe the change, don't specify the files.

2

Routing picks a model

The request is scored on size, scope, and intent, then sent to Flash or Pro.

3

Context is assembled

Project instructions from .acorn.md, git state, and prior turns, compacted if the window is tight.

4

The model calls tools

Reads files, edits lines, runs shell commands, searches the web, or calls an MCP server.

5

Results feed back

Tool output returns to the model, which decides what to do next — up to 25 iterations per turn.

6

Errors are recovered

A failed command comes back as an error the model can read and adapt to, rather than ending the turn.

7

The answer renders

Streamed as it arrives, with markdown and diffs formatted live.

Architecture

How the source is laid out, if you want to dig in.

acorn/
├── config/
│   ├── settings.py        — Models, permissions, safety rules
│   └── project_config.py  — .acorn.toml loader
├── core/
│   ├── agent.py           — Main brain: streaming agentic loop
│   ├── context.py         — Context window with auto-compaction
│   ├── costs.py           — Token usage and cost tracking
│   ├── planner.py         — Multi-step task planning
│   ├── router.py          — Signal-scored model routing (Flash vs Pro)
│   └── session.py         — Session persistence to ~/.acorn/sessions/
├── tools/
│   ├── filesystem.py      — Read, write, edit, search, list, diffs
│   ├── terminal.py        — Command execution with timeout
│   ├── shell.py           — Persistent shell session
│   ├── web.py             — Web search and page fetching
│   ├── mcp.py             — Model Context Protocol client
│   └── git_tools.py       — Git-aware project understanding
├── ui/
│   └── terminal_ui.py     — Terminal UI with markdown rendering
└── main.py                — CLI entry point

Troubleshooting

Common problems and their fixes.

command not found: acorn

The install directory isn't on your PATH. Try python -m acorn.main, or reinstall with pip install --user acorn-agent and add ~/.local/bin to PATH.

ModuleNotFoundError: No module named 'acorn'

Running from a clone rather than an install. Run pip install -e . from the repo root.

CERTIFICATE_VERIFY_FAILED during web search

Your Python has no usable CA bundle — common on stock macOS Python. Fixed in 2.3.1, which falls back to certifi. Upgrade with pip install --upgrade acorn-agent.

404 NOT_FOUND on the model

Gemini 3.1 requires location = "global", which is the default. If you set a regional location in .acorn.toml, remove it.

Permission denied from gcloud

Run gcloud auth application-default login, and confirm you have the Vertex AI User role on the project.

Vertex AI API not enabled

Run gcloud services enable aiplatform.googleapis.com on the project.

A session won't resume

Delete ~/.acorn/sessions/ and restart. Sessions are a cache, not source of truth — nothing else is lost.

cd doesn't stick between commands

The persistent shell is off. Check you didn't pass --no-shell or set shell.persistent = false, and run /shell to see the current mode.

An MCP server didn't load

Run /mcp to see connection status. A server that fails to start is skipped so it can't block the session — check the command and args in your mcp.json resolve on PATH.

FAQ

What is Acorn?

An autonomous coding agent that lives in your terminal. It reads your code, writes files, runs commands, and refactors across a whole codebase — powered by Google's Gemini.

How much does it cost?

Acorn is free and open-source; you pay only for API usage. A free Gemini API key covers getting started, and smart routing keeps cost down by sending simple requests to Flash instead of Pro.

Is it safe to use?

Actions run through a three-tier permission system. Reads are free, writes and unknown commands ask first, and destructive commands are blocked outright. See the Safety section for detail.

Which languages does it support?

It's language-agnostic — it reads and edits files regardless of language, and picks up conventions from the code it's looking at.

Can I use it on an existing project?

Yes. cd into the project and run acorn. Adding a .acorn.md with your conventions makes it noticeably better on a codebase it hasn't seen.

Does it need a GCP account?

No. A free Gemini API key is enough. Vertex AI is there if you need enterprise billing, IAM, or data-residency controls.

Is my code sent anywhere?

Only the file contents and commands the agent actually reads are sent to the Gemini API to answer your request. There's no telemetry and nothing is sent anywhere else.

Changelog

Release notes, newest first.

2.3.1

LatestJuly 2026
  • Persistent shell — cd, exports, and venv activation carry across commands
  • Web search and page fetching built in, with no API key required
  • MCP support — plug in any Model Context Protocol server
  • Model routing rewritten to score requests on size, scope, and intent
  • Colored diffs with line numbers for every file change
  • Animated thinking status while the model works
  • Fixed markdown rendering raw asterisks while streaming
  • Fixed TLS verification so web search works on stock macOS Python

2.2.0

API key auth
  • Gemini API key support — no GCP project needed to get started
  • Real-time streaming — tokens appear as they're generated
  • Project instructions via .acorn.md for persistent context
  • Update notifications when a new version is available
  • New /config command to inspect current settings

2.1.0

Smart routing
  • Smart model routing for cost optimization
  • Context window management with auto-compaction
  • Improved surgical file editing
  • Undo support for file changes
  • Better error recovery and auto-retry

2.0.0

Major update
  • Upgraded to Gemini 3.1 Pro
  • Streaming responses
  • Session persistence
  • Image and screenshot analysis
  • Permission system

1.0.0

Initial release
  • File reading and editing
  • Command execution
  • Git-aware project understanding

For Collaborators

Setting up a development environment.

Clone and install

git clone https://github.com/andamagodwin/acorn.git
cd acorn
pip install -e .

Vertex AI setup (optional)

Only needed if you're working against a shared GCP project rather than your own API key.

gcloud auth login
gcloud auth application-default login

Then ask the project owner to grant you the Vertex AI User role.

Granting access (project owner)

gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="user:their-email@example.com" \
  --role="roles/aiplatform.user"

Or in the console: IAM & Admin → IAM → Grant Access → Role: “Vertex AI User”.

License

Acorn is released under the MIT License.