Quick Start

Get up and running with Acorn in under a minute.

1. Install from PyPI

pip install acorn-agent

2. Run Acorn

acorn

3. Set your API key (optional)

export GEMINI_API_KEY="your-key-here"

Get a free key at aistudio.google.com/apikey. Or skip this — Acorn will guide you through setup on first run (API key or Vertex AI).

Installation

Acorn requires Python 3.11 or higher and either a Gemini API key or a GCP project.

Prerequisites

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

Install with pip

pip install acorn-agent

Verify Installation

acorn --version

Configuration

Configure Acorn using .acorn.toml (settings) and .acorn.md (instructions) in your project root.

.acorn.toml — Project Settings

[model]
pro = "gemini-3.1-pro-preview"
flash = "gemini-3-flash-preview"
temperature = 0.2

[routing]
enabled = true
threshold = 200

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

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

.acorn.md — Project Instructions

Give Acorn persistent context about your project. This gets injected into the system prompt so Acorn always respects your conventions.

# Project: MyApp

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

## Conventions
- Use snake_case for Python, camelCase for TS
- 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_KEY — Gemini API key (simplest auth)
ACORN_PROJECT — GCP project ID (Vertex AI mode)
GOOGLE_CLOUD_PROJECT — Alternative GCP project env var

Usage

Learn how to use Acorn effectively in your development workflow.

Basic Commands

acorn

Start an interactive session with Acorn.

Session Management

acorn --session my-session

Start a named session that can be resumed later.

List Sessions

acorn --list-sessions

View all available sessions.

Features

Acorn provides powerful features to enhance your development workflow.

Streaming Responses

See output as it's generated — no waiting for complete responses.

Smart Model Routing

Flash for simple questions, Pro for complex tasks — saves ~70% on costs.

Surgical File Editing

Modifies specific lines, not entire files — precise and safe.

Session Persistence

Resume conversations where you left off.

Undo Support

Revert the last file change instantly.

Safety

Acorn includes a permission system to ensure safe operations.

Safe Mode

Read-only operations are allowed without confirmation.

Ask Mode

Destructive operations require user confirmation.

Deny Mode

Destructive operations are blocked entirely.

Commands

Use these commands within the Acorn session to control behavior.

Command	What it does
/help	Show all commands
/model <name>	Switch model (or list available)
/cost	Show session cost breakdown
/status	Token usage, routing stats, cost
/plan	Show current task execution plan
/undo	Revert the last file change
/clear	Reset context and session
/sessions	List saved sessions
/routing on\|off	Toggle smart routing
/config	Show current configuration
/exit	Quit

Changelog

Recent updates and release notes for Acorn.

Version 2.2.0

Latest Release

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

Version 2.1.0

Smart Routing

Added smart model routing for cost optimization
Improved context window management with auto-compaction
Enhanced surgical file editing capabilities
Added undo support for file changes
Better error recovery and auto-retry

Version 2.0.0

Major Update

Upgraded to Gemini 3.1 Pro model
Added streaming responses
Implemented session persistence
Added image/screenshot analysis
Introduced permission system

Version 1.0.0

Initial Release

Initial release of Acorn
Basic file reading and editing
Command execution
Git-aware project understanding

FAQ

Frequently asked questions about Acorn.

What is Acorn?

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

How much does it cost?

Acorn is free and open-source — you only pay for API usage. Use a free Gemini API key to start, or Vertex AI for enterprise. Smart routing saves ~70% by using Flash for simple questions.

Is it safe to use?

Acorn includes a 3-tier permission system (safe/ask/deny) for secure operations. Blocked commands like `rm -rf /` are permanently blocked, and file writes require confirmation by default.

What programming languages does it support?

Acorn is language-agnostic and can work with any programming language. It understands your code structure and can edit files regardless of the language.

Can I use it with my existing project?

Yes! Simply navigate to your project directory and run `acorn`. Acorn will analyze your codebase and help you with any tasks.

How do I configure Acorn?

Use .acorn.toml for model/routing/permission settings and .acorn.md for project instructions and conventions. Both go in your project root.

For Collaborators

How to join the Acorn project and set up collaboration.

Joining the Project

Get added as a collaborator on the GitHub repo
Clone and install:
git clone https://github.com/andamagodwin/acorn.git cd acorn pip install -e .
Set up GCP authentication:
gcloud auth login gcloud auth application-default login
Ask the project owner to add you to the GCP project with the "Vertex AI User" role in IAM
Run acorn from any directory

IAM Setup (For Project Owner)

To add a collaborator to your GCP project:

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

Or in the console: IAM & Admin > IAM > Grant Access > Role: "Vertex AI User"

Architecture

Overview of the Acorn codebase structure.

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          — Smart model routing (Flash vs Pro)
│   └── session.py         — Session persistence to ~/.acorn/sessions/
├── tools/
│   ├── filesystem.py      — Read, write, edit, search, list
│   ├── terminal.py        — Command execution with timeout
│   └── git_tools.py       — Git-aware project understanding
├── ui/
│   └── terminal_ui.py     — Terminal UI with markdown rendering
└── main.py                — CLI entry point

How It Works

The workflow of how Acorn processes your requests.

You type a message

Start a conversation with Acorn about your code.

Smart routing

Acorn routes it to Flash (simple) or Pro (complex) based on the request.

Tool execution

The model calls tools — reads files, edits code, runs commands.

Iterative processing

Tool results feed back for up to 25 iterations per turn.

Error recovery

If something fails, it sees the error and adapts.

Response rendering

Final response renders with markdown formatting.

Troubleshooting

Common issues and their solutions.

Problem	Fix
ModuleNotFoundError: No module named 'acorn'	Run `pip install -e .` from the acorn directory
404 NOT_FOUND model error	Gemini 3.1 requires `location="global"` (already set)
Permission denied on gcloud	Run `gcloud auth application-default login`
Vertex AI API not enabled	Run `gcloud services enable aiplatform.googleapis.com`
Session won't resume	Delete `~/.acorn/sessions/` and restart

License

MIT License