# CodeCraft

A self-hosted, web-based coding harness for AI models – in the spirit of Claude Code and
opencode, usable from any browser and installable as a PWA.

- **Any model**: Anthropic (native Messages API), Google Gemini, opencode Go, fal.ai,
  OpenRouter and self-hosted models (Ollama, vLLM, llama.cpp, LM Studio) through
  OpenAI-compatible endpoints.
- **Agent loop with tools**: read, write, edit, list, glob, grep, bash, web_fetch,
  todo_write, ask_user, task (subagents), skill – plus every tool of your MCP servers.
- **Modes**: `build` (full access), `plan` (read-only, proposes a plan), `craft`
  (study a target → build your own version → check visually → refine), and custom
  agents.
- **Human in the loop**: permission requests (with diffs) and questions from agents *and*
  MCP servers (elicitation) are forwarded to the UI; optional browser notifications.
- **MCP**: stdio and Streamable HTTP servers, configured in the UI or the config file.
- **Statistics**: every model request is recorded (tokens in/out, cache, time to first
  token, prefill and output speed, cost per model price) – per chat and in a dashboard
  with daily charts and a weekday × hour heatmap.
- **Claude Code compatible project files**: `AGENTS.md`, `CLAUDE.md`,
  `.claude/{agents,commands,skills}` (and `.codecraft/…`).
- **Configuration** in a commented TOML file that the web UI edits in place (comments
  are preserved).
- **i18n**: English and German; adding a language is one file.

## Quick start (Docker)

```sh
cp .env.example .env          # set CODECRAFT_TOKEN, WORKSPACE and provider keys
docker compose up -d --build
```

Open `http://<host>:8787`, sign in with the token and pick a project directory. On first
start the commented default config is written to `data/config.toml`. Put the service behind
a TLS reverse proxy for remote access – the PWA install prompt requires HTTPS.

## Configuration

See [`config.example.toml`](config.example.toml) – every option is documented there.
Highlights:

- `[providers.<name>]` – `kind = "anthropic" | "openai"`, `base_url`, `api_key`
  (`${ENV}` references recommended), optional `models` with context size, effort and
  prices per 1M tokens. Without `models`, the list is fetched from the provider.
- `[mcp.<name>]` – `type = "stdio"` (command/args/env) or `"http"` (url/headers).
- `[permissions]` – `allow` / `ask` / `deny` per tool (globs such as `mcp__*`), plus
  `[permissions.bash_rules]` for shell command patterns. Compound commands are only
  auto-allowed when every part is allowed.
- `[agents.<name>]` – custom modes and subagents.
- `[craft]` – Chromium binary, screenshot widths, clean room vs. deep mode.

## Development

Requirements: Rust (edition 2024), Node ≥ 20.19.

```sh
# backend (writes ./data/config.toml on first start)
cd server && CODECRAFT_CONFIG=../data/config.toml cargo run

# frontend with hot reload, proxies /api to 127.0.0.1:8787
cd web && npm install && npm run dev
```

For local development set `bind = "127.0.0.1:8787"` and `workspace` to your projects
directory in `data/config.toml`.

Tests: `cd server && cargo test`, type check: `cd web && npx tsc --noEmit`.

## Architecture

```
server/ (Rust, axum + tokio)
  provider/   Anthropic + OpenAI-compatible streaming clients
  runner.rs   agent loop: streaming, tool execution, permissions, subagents, compaction
  tools/      built-in tools (fs, bash, web, agent, craft)
  mcp.rs      MCP client (stdio, Streamable HTTP, elicitation)
  prompts.rs  agents/modes, system prompt, AGENTS.md, slash commands, skills
  permission.rs, config.rs (toml + toml_edit), store.rs (SQLite), api.rs (REST + WebSocket)
web/ (React + Vite, PWA)
  src/components  chat, composer, permission/question cards, settings, statistics
  src/i18n        en (reference), de
```

The server streams all events over one WebSocket (`/api/ws`); the UI reconnects and
resyncs automatically, so long-running agents keep going when the browser is closed.

## Roadmap

- Background shell processes, file checkpoints/undo, `@file` mentions
- MCP OAuth, resources and prompts; remote MCP over SSE (legacy)
- Hooks (pre/post tool), output styles, per-project config overrides
- Image generation tools (fal.ai), OpenAI Responses API
- Multi-user accounts