Gcode

A lightweight coding agent that writes, reviews, and iterates on code. Gets sharper the more you use it.

Gcode operates inside a container with a persistent workspace volume. Each project is a git repo. Each task gets its own worktree. All code persists across container restarts.

Get Started

# Clone the repo
git clone https://github.com/agno-agi/gcode.git && cd gcode

# Add OPENAI_API_KEY
cp example.env .env
# Edit .env and add your key

# Start the application
docker compose up -d --build

No data loading required — the workspace starts empty and Gcode creates projects as you ask.

Confirm Gcode is running at http://localhost:8000/docs.

Connect to the Web UI

1. Open os.agno.com and login
2. Add OS → Local → http://localhost:8000
3. Click "Connect"

Try it:

• Build a URL shortener with FastAPI and tests
• What projects exist in the workspace?
• Review the code in my most recent project
• Fix any failing tests in url-shortener

How It Works

Gcode owns its workspace entirely — you interact through conversation, not an editor.

You: "Build a URL shortener with FastAPI"
     ↓
Gcode: mkdir /workspace/url-shortener && git init
     ↓
Creates worktree → writes code → runs tests → commits
     ↓
Reports what it built, what tests pass, and the git log

Each task gets its own git worktree — isolated branch, isolated files. Switch between tasks without losing state.

Self-Learning

Gcode improves with use through two complementary systems:

| System | Stores | How It Evolves | |--------|--------|----------------| | Knowledge | Project metadata, conventions | Curated by you + Gcode | | Learnings | Error patterns, codebase quirks, user preferences | Managed by Learning Machine automatically |

When Gcode discovers that a project uses pytest with fixtures in conftest.py, it saves that. Next time you ask about tests, it already knows.

GitHub Access

Gcode can clone and push to GitHub repos using a fine-grained Personal Access Token.

See GITHUB_ACCESS.md for setup instructions.

Deploy to Railway

Requires:

• Railway CLI
• OPENAI_API_KEY set in your environment

railway login

./scripts/railway_up.sh

The script provisions PostgreSQL, configures environment variables, and deploys your application.

Connect to the Web UI

1. Open os.agno.com
2. Click "Add OS" → "Live"
3. Enter your Railway domain

Manage deployment

railway logs --service agent_os      # View logs
railway open                         # Open dashboard
railway up --service agent_os -d     # Update after changes

To stop services:

railway down --service agent_os
railway down --service pgvector

Architecture

gcode/
├── app/main.py        # FastAPI + AgentOS entry point
├── gcode/agent.py     # Agent definition (CodingTools + ReasoningTools + LearningMachine)
├── db/                # PostgreSQL session (for knowledge/learnings storage)
├── compose.yaml       # Docker services (api + postgres)
└── Dockerfile         # Non-root container with git, workspace volume

Key components:

• CodingTools: file read/write/edit, shell, grep, find, ls
• ReasoningTools: think tool for complex debugging chains
• LearningMachine: saves and retrieves project conventions, gotchas, user preferences
• Workspace: persistent Docker volume at /workspace

Local Development

For development without Docker:

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Setup environment
./scripts/venv_setup.sh
source .venv/bin/activate

# Start PostgreSQL (required)
docker compose up -d gcode-db

# Run the app
python -m app.main

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | OPENAI_API_KEY | Yes | OpenAI API key | | GITHUB_TOKEN | No | Fine-grained PAT for cloning/pushing repos | | DB_* | No | Database config (defaults to localhost) |

Learn More

• Agno Docs
• Discord