quickcode

# quickcode

An AI-powered coding agent platform built in Rust. Connects to LLM providers (Anthropic, OpenAI, Google, and more) and exposes a TUI and HTTP API for autonomous code editing, shell execution, file management, and language server integration.

> **Alpha software — not production ready.**
> quickcode is under active development. APIs, config formats, and storage schemas may change without notice between versions. We welcome early adopters and contributors — see [Contributing](#contributing) below.

---

## Features

### Core agent loop
- **Multi-turn AI conversations** with full message history and per-session context
- **ReAct-style agent loop** — Reason → Act (tool calls) → Observe → repeat, up to 50 steps per message
- **Session compaction** — automatically summarises old messages when context window fills up
- **Session forking, revert, and abort** — branch conversations, undo agent steps, cancel in-flight runs
- **Snapshot tracking** — per-step git-based change tracking with diff/patch storage

### Tools available to agents
| Tool | Description |
|------|-------------|
| `read` | Read files with optional line ranges |
| `write` | Write files with LSP diagnostics feedback |
| `edit` | In-place find-and-replace editing |
| `bash` | Shell command execution via PTY (real terminal emulation) |
| `glob` | File pattern matching (capped at 100 results) |
| `grep` | Ripgrep-powered content search (capped at 100 results) |
| `web_fetch` | Fetch a URL (5 MB cap, HTML-to-text extraction) |
| `web_search` | Web search via configured search provider |
| `apply_patch` | Apply unified diffs to files |
| `ask_user` | Request clarification from the user |
| `subtask` | Spawn a sub-agent session for parallel workloads |
| `todo_read` / `todo_write` | Manage a per-session task list |
| `lsp` | Language server operations (hover, go-to-definition, diagnostics) |
| `memory_write` | Store a key-value pair in session, project, or global memory |
| `memory_read` | Retrieve a stored memory entry |
| `memory_delete` | Delete a memory entry |
| `memory_list` | List memory entries, with optional wildcard key filter |

### Memory system
- **Short-term (session)** — key-value pairs tied to the current conversation, cleaned up automatically
- **Long-term (project)** — persist across all sessions for a project; injected into every session's system prompt
- **Global** — available in all projects; useful for user preferences and cross-project conventions
- `POST /project/init` — scans your project, calls the LLM, and writes a `QUICKCODE.md` to the project root; this file is automatically included in every future session's context

### LLM providers
- **Anthropic** — Claude 3.5 / Claude 3 family (most complete support)
- **OpenAI** — GPT-4o, GPT-4, o-series reasoning models
- **Google** — Gemini 1.5 / 2.0 family
- **OpenRouter** — unified access to 200+ models
- **Azure OpenAI** — Azure-hosted deployments
- Model catalog auto-fetched from [models.dev](https://models.dev) and cached locally
- Model variant selection — picks the largest context window available for a given model

### Permission system
- Rule-based allow / deny / ask per tool and file-path pattern (wildcard)
- Global config → session-level → agent-level rule merging
- Doom-loop detection — stops an agent repeating the same tool call 3+ times in a row

### Storage & persistence
- SQLite database at `~/.local/share/quickcode/quickcode.db`
- Tables: `project`, `session`, `message`, `part`, `todo`, `permission`, `memory`
- Per-session token/cost tracking

### Server & API
- **HTTP API** (axum) with SSE event streaming and optional WebSocket
- **Basic auth** — password-protected server via `QUICKCODE_SERVER_PASSWORD`
- **Workspace support** — multi-tenant isolation via `?workspace=` or `X-quickcode-Workspace` header
- **MCP server** — exposes quickcode tools over the Model Context Protocol (stdio)
- OpenAPI doc endpoint at `GET /doc`

### Developer experience
- **TUI** — ratatui-based terminal UI with chat, welcome screen, markdown rendering
- **LSP client** — JSON-RPC language server integration with push-diagnostics (`textDocument/publishDiagnostics`)
- **Config** — JSONC (comments + trailing commas), `{env:VAR}` and `{file:path}` substitutions
- **Session sharing** — stable share URLs via `POST /session/:id/share`
- **VCS** — git diff and status endpoints

---

## Status

quickcode is **alpha software**. Here is what that means in practice:

- The core agent loop, tool execution, and session persistence work reliably.
- **Incoming breaking changes**: we are actively redesigning several subsystems (MCP client integration, LSP wiring, plugin API, config schema). Breaking changes will happen without a deprecation period until we reach v1.0.
- The HTTP API is not yet considered stable; field names and response shapes may change.
- The TUI is functional but minimal — UI polish is planned.
- Windows support is untested. macOS and Linux are the primary targets.

We tag releases with `0.x.y` and document breaking changes in the commit log.

---

## Getting Started

### Prerequisites

- Rust 1.75+ (`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`)
- `git` (for VCS and snapshot features)
- An API key for at least one LLM provider

### Installation

```bash
git clone https://github.com/your-org/quickcode
cd quickcode
cargo build --release
```

The binary will be at `target/release/quickcode`.

Optionally add it to your `PATH`:

```bash
cp target/release/quickcode ~/.local/bin/quickcode
```

### Configuration

Set your API key in the environment (or in the config file):

```bash
export ANTHROPIC_API_KEY=sk-ant-...   # Claude
export OPENAI_API_KEY=sk-...          # GPT-4o
export GOOGLE_API_KEY=...             # Gemini
```

Optionally create a config file at `~/.config/quickcode/config.jsonc`:

```jsonc
{
  // Default model ("provider/model_id")
  "model": "anthropic/claude-3-5-sonnet-20241022",

  // Permission rules — last-match-wins
  "permission": [
    { "permission": "bash", "pattern": "*", "action": "allow" }
  ],

  // Agent-specific overrides
  "agent": {
    "build": { "model": "openai/gpt-4o", "temperature": 0.5 }
  }
}
```

### Initialise a project

Run this once to generate a `QUICKCODE.md` file in your project root. It will be automatically included in every future agent session as project context:

```bash
curl -X POST "http://localhost:4096/project/init?directory=$(pwd)"
```

Or from the TUI, type `/init` (if the command is wired to a slash command).

---

## Running

### TUI mode (default)

```bash
# In your project directory:
quickcode

# Or specify a directory:
quickcode --dir /path/to/project
```

### Server mode (headless)

```bash
quickcode serve --port 4096
```

The API will be available at `http://localhost:4096`.

### Options

```
quickcode [OPTIONS] [COMMAND]

Commands:
  run    Start in TUI mode (default)
  serve  Start HTTP server only

Options:
  -d, --dir <DIR>          Working directory [default: current dir]
  -p, --port <PORT>        HTTP server port [default: 4096]
      --log-level <LEVEL>  Log level [default: info]
  -h, --help               Print help
  -V, --version            Print version
```

---

## HTTP API

The server exposes a REST API on port 4096 (configurable). All events are also available via SSE on `GET /event`.

### Sessions

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/session` | List sessions (filter by `?projectId=`, `?workspace=`, `?archived=`) |
| `POST` | `/session` | Create a session |
| `GET` | `/session/:id` | Get a session |
| `DELETE` | `/session/:id` | Delete a session |
| `PATCH` | `/session/:id` | Update title or permission rules |
| `POST` | `/session/:id/chat` | Send a message — returns SSE stream |
| `POST` | `/session/:id/compact` | Trigger manual compaction |
| `POST` | `/session/:id/abort` | Abort the running agent |
| `POST` | `/session/:id/fork` | Fork a session |
| `POST` | `/session/:id/revert` | Rev

[truncated…]