Vera

Autonomous software engineering agent built on the pi-agent framework. Vera can plan and execute complex development tasks, integrate with Slack/Linear/GitHub, and recover transparently from crashes.

Architecture

                    ┌──────────┐  ┌──────────┐   ┌──────────┐
                    │  Slack   │  │  Linear  │   │  GitHub  │
                    └────┬─────┘  └────┬─────┘   └────┬─────┘
                         │             │              │
                    ┌────▼─────────────▼──────────────▼────-┐
                    │         Webhook Server (HTTP/WS)      │
                    ├──────────────────────────────────────-┤
                    │   Session Registry + Snapshotter      │
                    │   (crash-safe, atomic writes)         │
                    ├──────────────────────────────────────-┤
                    │         Agent Session                 │
                    │   ┌──────────────────────────────-┐   │
                    │   │  main (Opus)    ─ executor    │   │
                    │   │  slack (Opus)   ─ Slack agent │   │
                    │   │  linear (Opus)  ─ ticket agent│   │
                    │   │  planner (Opus) ─ research    │   │
                    │   │  architect(Opus)─ design      │   │
                    │   │  explorer(Haiku)─ context gath│   │
                    │   └──────────────────────────────-┘   │
                    ├──────────────────────────────────────-┤
                    │   Tools: read, edit, write, bash,     │
                    │   web_search, web_fetch, linear_*,    │
                    │   batch, delegate, write_todos,       │
                    │   write_plan, run_workflow ...        │
                    └──────────────────────────────────────-┘

Key design decisions:

• Plan-then-execute — The main agent delegates to a planner sub-agent for research and planning before implementing anything.
• Crash-safe sessions — Messages are snapshotted atomically on every turn. On restart, dangling tool calls get synthetic error results and the agent continues transparently.
• Sub-agent delegation — Explorer, planner, and architect agents run in subprocesses with their own tool sets, keeping the main agent's context clean.

Setup

bun install --frozen-lockfile

Required environment variables (in .env):

ANTHROPIC_API_KEY=...

Optional:

SLACK_APP_TOKEN=...       # Slack Socket Mode
SLACK_BOT_TOKEN=...       # Slack Web API
LINEAR_BOT_TOKEN=...      # Linear integration
BRAVE_API_KEY=...         # Web search (Brave)
LANGSMITH_TRACING=true    # LangSmith tracing
LANGSMITH_API_KEY=...

Usage

Server mode (Slack + Linear + GitHub + TUI + Crons)

bun run start

Terminal UI

bun run tui

Headless (single task, stdout output)

bun src/headless.ts "Fix the failing tests in src/auth"
bun src/headless.ts --cwd /path/to/repo --model anthropic/claude-opus-4-6 "task"
bun src/headless.ts --output-file result.txt "task"

Supports --cwd, --model, --output-file, --state-dir, --debug-requests. Instructions can also be piped via stdin (with optional base64: prefix).

Docker

docker build -t vera .
docker run -e ANTHROPIC_API_KEY=... vera

# Local dev with persistent workspace
docker-compose up

Evals

bun run eval --eval <eval-name>

Evals live in benchmarks/evals/, each with a task.yml defining sources, commands, and validations.

Project Structure

src/
├── index.ts                 # Server entry point (multi-integration)
├── headless.ts              # CLI entry point (single task)
├── recovery.ts              # Transparent session recovery
├── webhook-server.ts        # Shared HTTP server for webhooks
├── paths.ts                 # Resolves VERA_CONFIG_DIR / VERA_STATE_DIR
├── langfuse.ts, langsmith.ts, trace-scrubber.ts  # Tracing
├── metrics.ts               # Prometheus metrics
├── session/                 # Session subsystem
│   ├── index.ts             # createSession() — central factory
│   ├── snapshotter.ts       # Atomic message persistence
│   ├── registry.ts          # Active session tracking
│   ├── logger.ts            # JSONL session logs
│   ├── state.ts             # Atomic file helpers
│   ├── skills.ts            # Skill prompt injection
│   └── pruner.ts, disk-pruner.ts
├── tools/                   # Tool implementations
│   ├── index.ts             # createTools() — process-wide registration
│   ├── registry.ts          # ToolRegistry — per-session resolution
│   ├── builtin-tools.ts     # read/bash/edit/write wiring
│   ├── delegate.ts          # Loads agent definitions from src/agents/
│   ├── agent-session-runner.ts  # Sub-agent execution kernel
│   ├── batch.ts             # Parallel fan-out tool
│   ├── edit.ts, read.ts, write.ts
│   ├── web-search.ts, web-fetch.ts
│   ├── planning.ts, plan.ts # write_todos / write_plan
│   ├── linear-*.ts          # Linear API tools
│   ├── workflow/            # YAML workflow engine
│   └── cron/                # Cron scheduling
├── agents/                  # Agent definitions: main, slack, linear, planner, explorer, architect
├── slack/                   # Slack handler
├── linear/                  # Linear handler
├── github/                  # GitHub webhook handler
├── tui/                     # Terminal UI client
└── storage/                 # S3 / disk artifact storage

.vera/                       # Config (read-only) + state (mutable)
├── skills/                  # Reusable skill packages (SKILL.md + assets)
├── workflows/               # YAML workflow definitions
├── crons/                   # Scheduled task definitions
├── brain/                   # Long-term context loaded into agent prompts
├── sessions/                # Session snapshots + registry (state)
├── todos/, todos.json       # Planning tool output (state)
└── workspace/               # Persistent working directory (state)

harbor_agent/                # Harbor framework wrapper for benchmarks
benchmarks/                  # Eval framework and task definitions

Agent definitions live in src/agents/*.md (markdown + YAML frontmatter), not .vera/agents/. They are baked into the source tree, not config.

Testing

bun test                                           # Smoke tests
python -m pytest tests/test_harbor_agent.py -v     # Harbor wrapper tests

Deployment

Production runs on Fly.io with a persistent volume at /workspace. The Dockerfile compiles to standalone binaries (vera-server, vera-headless) on a minimal Debian runtime.

Harbor Integration

The harbor_agent/ directory contains a PiAgentSimple wrapper implementing Harbor's BaseInstalledAgent interface, used for running the agent in benchmark containers.