FastClaw AGENTS.md

AGENTS.md — FastClaw

What This Is

FastClaw is a Slack/Telegram bot backed by an autonomous AI agent (OpenAI Codex CLI). It receives messages from Slack or Telegram, queues them as tasks in a SQLite database, runs Codex in a sandboxed subprocess to produce answers, and posts the results back. It ships with an admin dashboard for configuration, monitoring, and approvals.

Production deployment: Railway (Docker).

---

Repo Layout

FastClaw/
├── grail/                      # Main Rust workspace (this is the product)
│   ├── Cargo.toml              # Workspace root
│   └── crates/
│       ├── grail-server/       # Core: web server, worker, admin UI, DB
│       │   ├── src/            # All Rust source (see below)
│       │   ├── (no templates)
│       │   └── migrations/     # SQLite migrations (applied on startup)
│       ├── grail-slack-mcp/    # MCP tool server for Slack API
│       └── grail-web-mcp/     # MCP tool server for Brave search + web fetch
├── frontend/                    # React admin dashboard source
├── codex/                      # Vendored OpenAI Codex CLI (Git submodule)
├── guardrails/                 # Vendored Guardrails AI library (Git submodule)
├── nanobot/                    # Vendored Nanobot agent (Git submodule)
├── coworker/                   # Coworker agent (Git submodule)
├── Dockerfile                  # Multi-stage: build Rust → Debian slim + Codex CLI
├── entrypoint.sh               # Drops privileges, runs grail-server
├── railway.json                # Railway deploy config (Dockerfile builder, healthcheck)
├── slack-app-manifest.yaml     # Slack app scopes and event subscriptions
└── .env.example                # All supported environment variables

---

Source Files (grail/crates/grail-server/src/)

File	Purpose
main.rs	Axum web server, /admin React SPA serving, admin JSON API mount, Slack/Telegram webhooks, health, Slack signature verification
worker.rs	Background task processor: claims tasks, builds Codex prompts, spawns Codex CLI subprocess, parses agent output, sends replies
db.rs	All SQLite operations (settings CRUD, task queue, sessions, cron, guardrails, approvals, secrets)
models.rs	Shared structs (Task, Session, Settings, etc.)
slack.rs	SlackClient — post messages, upload files, download files, fetch channel history
telegram.rs	Telegram webhook payload types and message-sending client
codex.rs	Codex CLI subprocess management: spawn, stream output, parse structured responses
codex_login.rs	ChatGPT device login / OAuth flow for Codex authentication
approvals.rs	Approval request lifecycle (create, decide, check)
config.rs	CLI args via clap (--port, --data-dir, etc.)
crypto.rs	AES-GCM encryption/decryption for stored secrets
secrets.rs	Secret retrieval (env vars → encrypted SQLite fallback)
guardrails.rs	Apply guardrail rules to shell commands before execution
cron_expr.rs	Cron expression parsing helpers
bootstrap.rs	First-run setup and data directory initialization