Richard ZinkandClaude Opus 5.5
f3a2fe3816
Rust backend (axum/tokio): agent loop with streaming, tools (fs, bash, web_fetch, todo, ask_user, subagents, skills, craft snapshots/compare), permissions with modes and rules, Anthropic + OpenAI-compatible providers, MCP client (stdio/HTTP, elicitation), SQLite sessions, usage statistics, compaction, commented TOML config editable via toml_edit. React PWA: chat with live streaming, permission/question cards, modes (build/plan/craft), settings for providers/models/prices/MCP/permissions, raw config editor, statistics dashboard, i18n (en/de). Docker setup. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
94 lines
4.2 KiB
Markdown
94 lines
4.2 KiB
Markdown
# 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
|