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. Enter your GCP Project ID

On first run, Acorn will prompt you for your GCP project ID. This is required to use Vertex AI.

Installation

Acorn requires Python 3.11 or higher and a Google Cloud Platform project with Vertex AI enabled.

Prerequisites

Python 3.11 or higher
Google Cloud Platform project
Vertex AI API enabled
Google Cloud credentials configured

Install with pip

pip install acorn-agent

Verify Installation

acorn --version

Configuration

Configure Acorn using a project-specific .acorn.toml file.

[project]
name = "my-project"
description = "My coding project"

[router]
model_pro = "gemini-2.0-flash-exp"
model_flash = "gemini-2.0-flash-exp"

[context]
max_tokens = 100000
compaction_threshold = 80000

Project Settings

name - Project name
description - Project description

Router Settings

model_pro - Model for complex tasks
model_flash - Model for simple tasks

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
/exit	Quit

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