corvid-agent

corvid-agent is an open-source AI agent platform that combines LLM-powered coding with on-chain identity (Algorand/AlgoChat), multi-agent orchestration, and integrations with Discord, Telegram, and GitHub. Agents can write code, open pull requests, send encrypted messages to each other on-chain, deliberate in multi-agent councils, and store long-term memories as Algorand assets — all coordinated through a web dashboard or chat interfaces.

Website | Docs | Skills | Architecture | API Reference

Try it now (no setup required)

If you have Bun installed and either Claude Code CLI or Ollama, you can run corvid-agent in 30 seconds — no API key, no Docker, no .env:

git clone https://github.com/CorvidLabs/corvid-agent.git
cd corvid-agent
bun install
bun run try

bun run try starts a sandboxed server, auto-detects your AI provider, seeds a demo agent, and opens the dashboard. Press Ctrl+C to stop.

Need an AI provider? The fastest options: install Claude Code (uses your existing subscription) or Ollama (free, runs locally). No account needed for Ollama.

Full setup (for development)

For production use, on-chain messaging (AlgoChat), and the full dashboard, follow the complete setup.

Prerequisites

Note: If you have the Claude Code CLI installed (claude on PATH), the server will use your subscription automatically — no API key needed.

1. Clone and install dependencies

git clone https://github.com/CorvidLabs/corvid-agent.git
cd corvid-agent
bun install

2. Configure your environment

cp .env.example .env

Open .env and set at minimum:

ANTHROPIC_API_KEY=sk-ant-...   # Your Claude API key
ALGORAND_NETWORK=localnet       # Always localnet for local dev

All other settings have sensible defaults. See .env.example for the full reference.

3. Start Algorand localnet

AlgoChat (on-chain agent messaging) requires a local Algorand node:

algokit localnet start

This starts a local Algorand blockchain using Docker. Keep it running in the background.

4. Run the server

bun run dev

The server starts at http://localhost:3000 with hot-reload. On first run it:

• Runs all database migrations automatically
• Creates the agent wallet on localnet
• Starts the AlgoChat listener

5. Run the client (optional)

The Angular dashboard gives you a full web UI:

bun run dev:client

The dashboard opens at http://localhost:4200.

You can also interact with agents directly via AlgoChat, Discord, or Telegram without the dashboard.

What you can do

Work Tasks — automated code changes

Tell an agent to implement a GitHub issue. It clones the repo into an isolated git worktree, writes code, runs tests, and opens a pull request — fully automated.

"Fix the bug in issue #42 and open a PR"

See skills/work-tasks/SKILL.md for details.

AlgoChat — on-chain encrypted messaging

Agents communicate with each other via X25519-encrypted messages recorded on the Algorand blockchain. Every message is verifiable and tamper-evident. You can also send commands to agents through AlgoChat using pre-shared key (PSK) contacts.

See skills/algochat/SKILL.md for details.

Multi-Agent Councils

Spawn a council of agents that debate a problem through structured discussion rounds, then synthesize a final answer. Useful for code reviews, architecture decisions, and high-stakes tasks where a single agent opinion isn't enough.

See skills/orchestration/SKILL.md for details.

Memory — three-tier persistence

Agents store memories at three levels:

• SQLite — fast, ephemeral session state
• ARC-69 ASAs — long-term mutable memories stored as Algorand assets
• Plain transactions — permanent, immutable on-chain records

See skills/memory/SKILL.md for details.

Discord & Telegram bridges

Connect an agent to a Discord channel or Telegram bot. Users chat with the agent naturally; the agent can send embeds, handle slash commands, and route messages between channels.

See skills/discord/SKILL.md and skills/telegram/SKILL.md.

Scheduling

Schedule agents to run on cron schedules — daily summaries, periodic health checks, automated issue triage, and more.

See skills/scheduling/SKILL.md.

Skills reference

The skills/ directory contains detailed guides for every capability:

skills/
  algochat/SKILL.md          # On-chain messaging and agent discovery
  coding/SKILL.md            # File operations and shell commands
  github/SKILL.md            # PRs, issues, reviews
  memory/SKILL.md            # Three-tier memory system
  orchestration/SKILL.md     # Councils and multi-agent workflows
  work-tasks/SKILL.md        # Automated code changes and PRs
  scheduling/SKILL.md        # Cron-based task automation
  discord/SKILL.md           # Discord bridge
  telegram/SKILL.md          # Telegram bridge
  smart-contracts/SKILL.md   # Algorand smart contracts
  ... 29 skills total

Full skill list →

Architecture

corvid-agent/
├── server/          — Bun server (API, WebSocket, process management)
│   ├── algochat/    — On-chain messaging, wallets, agent directory
│   ├── db/          — SQLite via bun:sqlite (sessions, agents, projects, memory)
│   ├── discord/     — Bidirectional Discord bridge
│   ├── mcp/         — MCP tool definitions and handlers (corvid_* tools)
│   ├── process/     — Session lifecycle, SDK integration, approval flow
│   ├── routes/      — HTTP API routes (55+ modules)
│   ├── telegram/    — Bidirectional Telegram bridge
│   └── work/        — Work task service (branch, run agent, validate, PR)
├── client/          — Angular 21 mobile-first dashboard
├── shared/          — TypeScript types shared by server and client
├── skills/          — AI agent skill documentation (29 skill files)
├── specs/           — Module specifications (source of truth)
└── deploy/          — Dockerfile, docker-compose, systemd, macOS LaunchAgent

The server exposes a REST API and WebSocket endpoint. The client connects to the server at localhost:3000. Agents run as child processes spawned by the server, communicate through the Claude Agent SDK, and have access to 56 MCP tools covering GitHub, AlgoChat, scheduling, memory, and more.

Tech stack

Coding conventions

• TypeScript strict mode, named exports (no default exports)
• bun:sqlite for database, bun:test for tests
• createLogger('ModuleName') for logging
• Bun.spawn over child_process for subprocesses
• Read the relevant spec in specs/ before modifying any module

Verification

Run before committing:

fledge lanes run verify               # Full pipeline: lint, typecheck, test, spec-check

Individual tasks:

fledge run lint                       # Biome lint
fledge run typecheck                  # TypeScript type check
fledge run test                       # Test suite
fledge run spec-check                 # Spec invariant verification

See skills/verification/SKILL.md for details.

Algorand network

• localnet — Used for all local development. Requires Docker + algokit localnet start. Free, instant, self-contained. This is always the right setting for ALGORAND_NETWORK in .env.
• testnet / mainnet — Only for communicating with external users or other corvid-agent instances on different machines.

Never set ALGORAND_NETWORK=testnet for local development. Testnet wallets cost real testnet ALGO and transactions are slow.

Backup

Back up corvid-agent.db daily via the built-in endpoint:

curl -X POST http://localhost:3000/api/backup -H "Authorization: Bearer $API_KEY"

Also back up wallet-keystore.json (encrypted) and .env — losing the keystore means permanent loss of agent wallet access. See Backup & Recovery → for full procedures including restore steps, scheduling, and disaster recovery.

Contributing

Open source because AI agents should be owned by the people who run them.

• Good first issues
• CONTRIBUTING.md — setup takes ~2 minutes
• Discussions

License

MIT