> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agno.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gcode

> Self-improving coding agent that operates inside a persistent workspace.

**Gcode is a self-improving coding agent designed for the post-IDE future.**

It writes, reviews, tests, and iterates on code inside a persistent workspace. You interact through conversation. Gcode owns the workspace entirely.

<Warning>
  Gcode is evolving rapidly. For the latest updates, see the [repo](https://github.com/agno-agi/gcode).
</Warning>

## How It Works

Gcode operates inside a container with a persistent workspace volume. Each project is a git repo. Each task gets its own worktree, so there's no state bleed between tasks and every change is auditable via git history.

```
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
```

<Tip>
  Gcode is sandboxed to `/workspace`. It cannot access your host filesystem. OS-level permissions enforce this boundary.
</Tip>

### Tools

Gcode combines three tool systems:

* **CodingTools** for file read/write/edit, shell, grep, find, and ls.
* **ReasoningTools** for structured debugging chains via the `think` tool.
* **LearningMachine** for saving and retrieving project conventions, error patterns, and user preferences.

### Self-Learning

Gcode improves with use through two complementary systems:

| System        | Stores                                                | How it evolves                                |
| ------------- | ----------------------------------------------------- | --------------------------------------------- |
| **Knowledge** | Project structure, testing conventions, build systems | Curated by you and refined by Gcode           |
| **Learnings** | Error patterns, codebase quirks, user preferences     | Managed automatically by the Learning Machine |

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.

## Run Locally

```bash theme={null}
git clone https://github.com/agno-agi/gcode.git && cd gcode

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

docker compose up -d --build
```

The workspace starts empty. Gcode creates projects as you ask.

Confirm it's running at `http://localhost:8000/docs`.

### Connect to the control plane

1. Open [os.agno.com](https://os.agno.com) and sign in
2. Click **Add OS** → **Local**
3. Enter `http://localhost:8000`

## Deploy to Railway

```bash theme={null}
railway login
./scripts/railway_up.sh
```

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

Then connect via the control plane:

1. Open [os.agno.com](https://os.agno.com)
2. Click **Add OS** → **Live**
3. Enter your Railway domain

## Example Prompts

Try these in the control plane:

* Build a FastAPI CRUD app with tests
* Add authentication to the existing project
* Fix any failing tests in url-shortener
* Review the codebase for security issues
* What conventions does this project use?

## Source

For architecture details and local development setup, see the [GitHub repo](https://github.com/agno-agi/gcode).