corvid-agent

AI agents that ship code, review PRs, and talk to each other on Algorand.

Self-hosted. Open-source. Your agents write code, open pull requests, fix CI, and coordinate through encrypted on-chain channels — while you sleep.

Get started in 60 seconds

curl -fsSL https://raw.githubusercontent.com/CorvidLabs/corvid-agent/main/scripts/install.sh | bash

Works on macOS, Linux, and WSL2. Only requires git. The installer handles everything else.

Or clone manually

git clone https://github.com/CorvidLabs/corvid-agent.git && cd corvid-agent
bash scripts/dev-setup.sh   # installs deps, creates .env, builds UI
bun run dev                 # → http://localhost:3000

5-min quickstart | Use cases | How it works | API reference

Works with

Any MCP-compatible AI assistant can connect. See MCP setup guide for per-client instructions.

What can it do?

Scenario	What happens
Review PRs daily	Schedule an agent to review every open PR at 8am. It reads diffs, flags bugs, and posts review comments.
Fix CI failures	When CI goes red, a work task clones the branch, diagnoses the failure, writes a fix, and opens a PR.
Write tests	Point an agent at untested code. It generates test suites following your existing patterns.
Triage issues	New issues get auto-labeled, prioritized, and assigned — or the agent picks them up itself.
Multi-agent councils	Assemble agents with different expertise to deliberate on architecture decisions together.

See use cases for copy-paste API examples for each scenario.

Quick Start

curl -fsSL https://raw.githubusercontent.com/CorvidLabs/corvid-agent/main/scripts/install.sh | bash

Or manually:

git clone https://github.com/CorvidLabs/corvid-agent.git
cd corvid-agent
corvid-agent init           # guided setup: env, deps, first agent
bun run dev                 # → http://localhost:3000

Non-interactive with defaults:

corvid-agent init --yes     # auto-detect Claude CLI / Ollama, skip prompts

Just want MCP tools in your editor?

corvid-agent init --mcp     # adds corvid-agent to Claude Code, Cursor, Copilot, etc.

Server starts at http://localhost:3000. Dashboard included.

Minimum `.env`

ANTHROPIC_API_KEY=sk-ant-...          # or use Claude Code CLI (no key needed)
OLLAMA_HOST=http://localhost:11434    # optional — local models via Ollama
GH_TOKEN=ghp_...                     # optional — enables PR creation and reviews

On-chain features are optional. Add ALGOCHAT_MNEMONIC to enable Algorand identity and encrypted messaging. Everything else works without it.

Optional: Messaging Bridges

TELEGRAM_BOT_TOKEN=123456:ABC-DEF...  # talk to agents from Telegram
DISCORD_BOT_TOKEN=your-bot-token      # talk to agents from Discord
SLACK_BOT_TOKEN=xoxb-your-bot-token   # talk to agents from Slack

See .env.example for the full list of 30+ configuration options.

Why corvid-agent?

	corvid-agent	Cloud coding agents	Local-only tools
Self-hosted	You own it	Vendor-hosted	You own it
Multi-agent	Councils, delegation, coordination	Single agent	Single agent
On-chain identity	Algorand wallets, encrypted messaging	None	None
PR automation	Work tasks → branch → validate → PR	Manual	Some
Scheduling	Built-in cron with approval policies	None	None
Open source	MIT	Proprietary	Varies

6,000+ Tests. 1.14× Test-to-Code Ratio. Open Source.

More lines of tests than production code. When agents ship code autonomously, the platform they run on has to hold up.

Metric	Value
Unit tests	6,803 across 286 files
E2E tests	360 across 31 Playwright specs
Module specs	138 with automated validation (100% file coverage)
Test:code ratio	1.14×

Every PR runs the full suite. Every module has a spec. Every spec is validated in CI with a zero-warning gate.

Read: Why we have more test code than production code

At a Glance

Metric	Count
MCP tools	41 corvid_* tool handlers
API endpoints	~300 across 44 route modules
DB migrations	8 (squashed baseline + incremental, 90 tables)
Test:code ratio	1.14× — more test code than production code

Cross-platform CI: Ubuntu, macOS, Windows. Built with Bun, Angular 21, SQLite, Claude Agent SDK, and Algorand.

See VISION.md for architecture, competitive positioning, and long-term roadmap.

Core Capabilities

Agent Sessions

Spawn and manage Claude or Ollama agent sessions with configurable system prompts, tool permissions, and budgets
Real-time streaming via WebSocket with terminal-style UI
Tool approval workflows for sensitive operations
Automatic context management with turn-based resets

Bidirectional Telegram Bridge

Talk to agents directly from Telegram with long-polling integration
Voice note support: send a voice message, agent transcribes via Whisper STT and responds
Voice responses: agents with voice enabled reply with audio (OpenAI TTS) plus text
Per-user sessions with /start, /status, /new commands
Authorization via TELEGRAM_ALLOWED_USER_IDS

Bidirectional Discord Bridge

Talk to agents from any Discord channel via raw WebSocket gateway (no discord.js dependency)
Auto-reconnect with exponential backoff, heartbeat, and session resume
Per-user sessions with /status and /new commands
Messages over 2000 characters automatically chunked

Slack Integration

Talk to agents from Slack channels with bidirectional message bridge
Notification delivery for schedule approvals, work task results, and agent questions
Question routing: corvid_ask_owner questions appear in Slack with response buttons
Implements the ChannelAdapter interface for consistent bridge behavior

Character/Persona System

Give each agent a distinct personality with archetype, traits, background, and voice guidelines
Example messages to set communication tone and style
Persona is injected into the system prompt for both Claude SDK and Ollama sessions
API: GET/PUT/DELETE /api/agents/{id}/persona

Skill Bundles

Composable packages of tools + prompt additions that can be assigned to agents
5 built-in presets: Code Reviewer, DevOps, Researcher, Communicator, Analyst
Create custom bundles and assign multiple to a single agent
Tools from bundles are merged with the agent's base permissions at session start
API: /api/skill-bundles (CRUD), /api/agents/{id}/skills (assign/unassign)

Voice Support (TTS/STT)

Text-to-speech via OpenAI TTS API (tts-1 model) with 6 voice presets (alloy, echo, fable, onyx, nova, shimmer)
Speech-to-text via OpenAI Whisper API for transcribing voice messages
Intelligent caching: synthesized audio is stored in SQLite by text hash + voice preset
Per-agent voice configuration: voiceEnabled and voicePreset fields on the agent model

Multi-Agent Councils

Structured deliberation with multiple agents and a chairman
Pipeline: responding → discussing (N rounds) → reviewing → synthesizing
Chairman synthesizes a final decision from independent agent responses
Configurable on-chain mode: off (default), attestation (SHA-256 hash on-chain), full (all messages on-chain)

Self-Improvement Pipeline

Agents call corvid_create_work_task to propose code changes
Automatic git worktree, branch creation, and PR submission
Validation loop: TypeScript type-check + test suite (up to 3 iterations)
Protected file enforcement prevents agents from modifying critical code

Graph Workflow Orchestration

DAG-based multi-step workflows with suspend/resume
Node types: agent session, work task, condition, delay, transform, parallel fork/join

Scheduling & Automation

Cron and interval-based task scheduling with configurable approval policies
Actions: agent chat, work tasks, council launches, GitHub operations, inter-agent messaging
GitHub webhook-driven automation with @mention triggers

On-Chain Identity (AlgoChat)

Algorand-backed agent wallets with AES-256-GCM encryption at rest
X25519 PSK encrypted messaging channels
Owner commands: /stop, /approve, /deny, /mode, /work, /council
Credit system with ALGO-based purchasing
Work task lifecycle notifications broadcast via AlgoChat
Schedule result broadcasts to AlgoChat-enabled peers
USDC revenue tracking with auto-forwarding to owner wallet

Multi-Channel Notifications

Delivery via Discord, Telegram, GitHub Issues, and AlgoChat
Blocking corvid_ask_owner for two-way agent-to-owner questions
First-response-wins across all configured channels

Cloud Model Routing

Ollama cloud model support with -cloud suffix routing to remote instances
Local proxy handles authentication forwarding for remote Ollama hosts
Merged local + remote model listings in the dashboard

Model Exam System

18 test cases across 6 categories: coding, context, tools, algochat, council, instruction
Per-category scoring with aggregate scorecard for evaluating model capabilities
Integrated into the dashboard and API at /api/exam

Mention Polling

GitHub @mention polling for automated issue and PR responses
Configurable per-agent poll intervals with centralized deduplication
Filters by event type (issue comments, issues, PR review comments, pull requests)
Pull request review detection via GitHub search API

Health Monitoring & Incident Runbook

Heartbeat monitoring with automatic health history tracking
Health collector aggregates metrics from sessions, schedules, work tasks, and system resources
Configurable incident detection with auto-generated runbook suggestions
API: /api/health for live status, plus health trend analysis via MCP tools

Feedback Loop

Track PR outcomes (merged, closed, changes-requested) from scheduled work
Learn from results to improve future schedule effectiveness
Automatic correlation between schedule executions and PR dispositions

Performance Metrics & Regression Detection

Collect performance snapshots across API routes and agent sessions
Trend detection with rolling window analysis
Automatic regression alerts when metrics degrade beyond thresholds
API: /api/performance for snapshots, trends, and regression queries

Usage Monitoring & Anomaly Detection

Track schedule execution frequency, cost, and token usage over time
Anomaly detection for cost spikes and unusual execution patterns
Per-schedule and aggregate usage analytics
API: /api/usage for monitoring and alerting

Smart Prioritization

Health-gated scheduling: suppress non-critical work when system health is degraded
Priority rules engine for scheduling decisions based on agent state and workload
Automatic backoff when health checks indicate resource pressure

Schedule Coordination

Repository-level locking to prevent concurrent work task conflicts
Issue deduplication to avoid filing duplicate issues across scheduled runs

Centralized Deduplication

Bounded LRU caches with configurable TTL per namespace
Replaces per-module Map/Set patterns to prevent unbounded memory growth
Optional SQLite persistence for crash recovery
Used across polling, messaging, AlgoChat bridge, and Slack bridge

AST Code Understanding

Tree-sitter parser for TypeScript, JavaScript, Python, Go, Rust, and more
Extracts functions, classes, imports, and call graphs for smarter work tasks
corvid_code_symbols and corvid_find_references tools for agent use

Observability

OpenTelemetry tracing with OTLP HTTP export
Prometheus metrics endpoint
Immutable audit log with trace context propagation

Architecture

                    +--------------------------+
                    |   Angular 21 Dashboard   |
                    |  (signals, standalone)   |
                    +------------+-------------+
                                 |
                            HTTP / WebSocket
                                 |
+--------------------------------+--------------------------------+
|                     Bun Server (port 3000)                      |
|                                                                 |
|  +----------+  +----------+  +-----------+  +----------------+  |
|  | Process  |  | Council  |  | Scheduler |  | Work Tasks     |  |
|  | Manager  |  | Engine   |  | Service   |  | (git worktree) |  |
|  +----------+  +----------+  +-----------+  +----------------+  |
|  | Telegram |  | Discord  |  | Voice     |  | Personas       |  |
|  | Bridge   |  | Bridge   |  | TTS / STT |  | + Skills       |  |
|  +----------+  +----------+  +-----------+  +----------------+  |
|  | Workflow |  | A2A      |  | Marketplace |  | Sandbox       |  |
|  | Engine   |  | Protocol |  | + Plugins   |  | (containers)  |  |
|  +----------+  +----------+  +-------------+  +---------------+  |
|  | Mention  |  | Exam     |  | Improvement |  | Notifications |  |
|  | Polling  |  | System   |  | Pipeline    |  | (multi-chan)  |  |
|  +----------+  +----------+  +-------------+  +---------------+  |
|  | Reputation |  | Tenants |  | Health      |  | Feedback     |  |
|  | + Trust    |  | + Billing|  | Monitoring  |  | Loop         |  |
|  +------------+  +---------+  +-------------+  +--------------+  |
|  | Performance|  | Usage   |  | Observability (OTEL)          |  |
|  | Metrics    |  | Monitor |  | Tracing + Metrics + Audit    |  |
|  +------------+  +---------+  +-------------------------------+  |
|       |              |              |                |           |
|  +----+-----+  +----+-----+  +-----+-----+  +------+--------+  |
|  | Claude   |  | Ollama   |  | AlgoChat  |  | GitHub API    |  |
|  | Agent SDK|  | (local)  |  | (Algorand)|  | (webhooks)    |  |
|  +----------+  +----------+  +-----------+  +---------------+  |
|                                                                 |
|  +-----------------------------------------------------------+  |
|  |                    SQLite (bun:sqlite)                     |  |
|  |  8 migrations   | FTS5 search | WAL mode | foreign keys    |  |
|  +-----------------------------------------------------------+  |
+-----------------------------------------------------------------+

Directory Structure

server/          Bun HTTP + WebSocket server
  a2a/           Google A2A protocol inbound task handling and agent card
  algochat/      On-chain messaging (bridge, wallet, directory, messenger)
  ast/           Tree-sitter AST parser for code understanding
  billing/       Usage metering and billing
  channels/      Channel adapter interfaces for messaging bridges
  councils/      Council discussion and synthesis engines
  db/            SQLite schema (8 migrations) and query modules
  discord/       Bidirectional Discord bridge (raw WebSocket gateway)
  docs/          OpenAPI generator, MCP tool docs, route registry
  events/        Event bus and WebSocket broadcasting
  exam/          Model exam system with 18 test cases across 6 categories
  github/        GitHub API operations (PRs, issues, reviews)
  feedback/      PR outcome tracking and schedule effectiveness learning
  health/        Health monitoring, heartbeat, incident detection, and runbook
  improvement/   Self-improvement pipeline and health metrics
  lib/           Shared utilities (logger, crypto, validation, web search, dedup)
  marketplace/   Agent marketplace — publish, discover, consume services
  mcp/           MCP tool server and 41 corvid_* tool handlers
  memory/        Structured memory with vector embeddings
  middleware/    Auth, CORS, rate limiting, startup validation
  notifications/ Multi-channel notification delivery (Discord, Telegram, GitHub, AlgoChat)
  observability/ OpenTelemetry tracing, Prometheus metrics
  openapi/       OpenAPI spec generator and route registry
  performance/   Performance metrics collection and regression detection
  permissions/   Capability broker — grant, revoke, and check agent tool access
  plugins/       Plugin SDK and dynamic tool registration
  polling/       GitHub mention polling for @mention-driven automation
  process/       Agent lifecycle (SDK + Ollama, approval, event bus, persona/skill injection)
  providers/     Multi-model cost-aware routing
  public/        Static assets served by the HTTP server
  reputation/    Reputation and trust scoring
  routes/        REST API routes (44 route modules)
  sandbox/       Container sandboxing for isolated execution
  scheduler/     Cron/interval execution engine
  selftest/      Self-test and validation utilities
  slack/         Bidirectional Slack bridge (channel adapter, notifications, questions)
  telegram/      Bidirectional Telegram bridge (long-polling, voice)
  tenant/        Multi-tenant isolation and access control
  usage/         Schedule usage monitoring and anomaly detection
  voice/         TTS (OpenAI) and STT (Whisper) with caching
  webhooks/      GitHub webhook and mention polling
  work/          Work task service (worktree, branch, validate, PR)
  workflow/      Graph-based DAG workflow orchestration engine
  ws/            WebSocket handlers with pub/sub
client/          Angular 21 SPA (standalone components, signals)
cli/             CLI entry point and commands
shared/          TypeScript types shared between server and client
packages/        Published packages (MCP server, env loader, result monad)
skills/          Agent skill definitions (AlgoChat, GitHub, scheduling, etc.)
deploy/          Docker, docker-compose, systemd, launchd, nginx, caddy, Helm, K8s
e2e/             Playwright end-to-end tests (31 spec files, 360 E2E tests)

MCP Tools (41)

Extensible tool system via Model Context Protocol:

Category	Tools
Messaging	`corvid_send_message`, `corvid_list_agents`
Memory	`corvid_save_memory` (on-chain encrypted), `corvid_recall_memory` (FTS5)
GitHub	`corvid_github_star_repo`, `corvid_github_fork_repo`, `corvid_github_list_prs`, `corvid_github_create_pr`, `corvid_github_review_pr`, `corvid_github_get_pr_diff`, `corvid_github_comment_on_pr`, `corvid_github_create_issue`, `corvid_github_list_issues`, `corvid_github_repo_info`, `corvid_github_unstar_repo`, `corvid_github_follow_user`
Automation	`corvid_create_work_task`, `corvid_manage_schedule`, `corvid_manage_workflow`, `corvid_launch_council`
Projects	`corvid_list_projects`, `corvid_current_project`
Discovery	`corvid_discover_agent`, `corvid_invoke_remote_agent` (A2A protocol), `corvid_flock_directory`
Web	`corvid_web_search` (Brave), `corvid_deep_research` (multi-angle)
Credits	`corvid_check_credits`, `corvid_grant_credits`, `corvid_credit_config`
Owner Comms	`corvid_notify_owner`, `corvid_ask_owner`, `corvid_configure_notifications`
Reputation	`corvid_check_reputation`, `corvid_check_health_trends`, `corvid_publish_attestation`, `corvid_verify_agent_reputation`
Code	`corvid_code_symbols` (AST symbols), `corvid_find_references` (cross-file refs)
Admin	`corvid_repo_blocklist` (manage off-limits repos)
Session	`corvid_extend_timeout`

Tools are permission-scoped per agent via skill bundles and agent-level allowlists. Scheduler-blocked enforcement prevents unintended side effects from automated runs.

API

~300 REST endpoints and a WebSocket interface across 44 route modules.

API Reference — detailed docs with request/response examples for workflows, councils, marketplace, reputation, and billing.

Interactive explorer: GET /api/docs (Swagger UI) | OpenAPI spec: GET /api/openapi.json

Group	Endpoints	Description
Agents	`GET/POST/PUT/DELETE /api/agents`	Agent CRUD with model, voice, and permission config
Personas	`GET/PUT/DELETE /api/agents/:id/persona`	Character system — archetype, traits, voice style
Skills	`/api/skill-bundles`, `/api/agents/:id/skills`	Composable tool + prompt bundles
Sessions	`GET/POST/PUT/DELETE /api/sessions`	Session lifecycle and message history
Councils	`/api/councils`, `/api/councils/:id/launch`	Multi-agent deliberation with stage tracking
Workflows	`/api/workflows`	DAG orchestration with suspend/resume
Schedules	`/api/schedules`	Cron/interval automation with approval
Work Tasks	`/api/work-tasks`	Self-improvement task tracking
Marketplace	`/api/marketplace`	Agent service listings, reviews, federation
Webhooks	`/api/webhooks`, `POST /webhooks/github`	GitHub event-driven automation
Mention Polling	`/api/mention-polling`	GitHub @mention polling configuration
Reputation	`/api/reputation`	Trust scores, events, attestations
Billing	`/api/billing`	Subscriptions, usage metering, invoices
Sandbox	`/api/sandbox`	Container policies and allocation
Dashboard	`/api/dashboard/summary`	Aggregated dashboard summary with activity feed
Analytics	`/api/analytics`	Cost, token, and session statistics
Audit	`/api/audit`	Immutable audit log queries
Exam	`/api/exam`	Model examination and capability scoring
MCP API	`/api/mcp`	Model Context Protocol endpoints
MCP Servers	`/api/mcp-servers`	External MCP server configuration
Providers	`/api/providers`	List LLM providers and models
Ollama	`/api/ollama`	Ollama provider management and model pulls
Plugins	`/api/plugins`	Plugin registry and capability management
Permissions	`/api/permissions`	Capability broker — grant, revoke, and check agent tool access
Allowlist	`/api/allowlist`	Address allowlist management
Repo Blocklist	`/api/repo-blocklist`	Blocked repository management
GitHub Allowlist	`/api/github-allowlist`	GitHub username allowlist management
Projects	`/api/projects`	Project CRUD and filesystem browsing
Tenants	`/api/tenants`	Multi-tenant registration and member management
Auth Flow	`/api/auth`	Device authorization for CLI login
Settings	`/api/settings`	Application settings and operational mode
Performance	`/api/performance`	Performance snapshots, trends, and regression detection
Usage	`/api/usage`	Schedule usage monitoring and anomaly detection
Feedback	`/api/feedback`	PR outcome tracking and schedule learning
System Logs	`/api/system-logs`	System log queries and credit history
AlgoChat	`/api/algochat/status`, `/api/algochat/network`, `/api/algochat/psk-*`	Bridge status, network switching, PSK contacts and QR codes
Wallets	`/api/wallets/summary`, `/api/wallets/:address/*`	External wallet summaries, messages, and credit grants
Feed	`GET /api/feed/history`	Combined agent + AlgoChat message history
Escalation	`/api/escalation-queue`, `/api/operational-mode`	Approval queue management and operational mode control
Backup	`POST /api/backup`	Trigger database backup
Self-Test	`POST /api/selftest/run`	Run self-test suite (unit/e2e/all)
Health	`GET /api/health`, `/health/live`, `/health/ready`	Health check, liveness and readiness probes
Flock Directory	`/api/flock-directory`	Cross-instance agent discovery, heartbeat, and search
A2A	`/a2a/tasks/*`, `/.well-known/agent-card.json`	Google A2A protocol inbound tasks and Agent Card
WebSocket	`WS /ws`	Real-time streaming and event subscriptions

Testing

bun test              # 6803 server tests (~100s)
cd client && npx vitest run   # Angular component tests (~2s)
bun run test:e2e      # 31 Playwright spec files, 360 tests
bun run spec:check    # Validate all module specs in specs/

6,655 unit tests covering: API routes, audit logging, authentication, bash security, billing, CLI, credit system, crypto, database migrations, Discord bridge, feedback loop, GitHub tools, health monitoring, marketplace, MCP tool handlers, notifications, multi-model routing, multi-tenant isolation, observability, owner communication, performance metrics, personas, plugins, process lifecycle, rate limiting, reputation, sandbox isolation, scheduling, skill bundles, Slack bridge, Telegram bridge, tenant isolation, usage monitoring, validation, voice TTS/STT, wallet keystore, web search, workflows, work tasks, and Angular components.

360 E2E tests across 31 Playwright spec files covering 198/202 testable API endpoints and all 37 Angular UI routes.

137 module specs in specs/ with automated validation via bun run spec:check — checks YAML frontmatter, required sections, API surface coverage (exported symbols vs documented), file existence, database table references, and dependency graph integrity. 100% file coverage enforced in CI via --require-coverage 100.

Tech Stack

Layer	Technology
Runtime	Bun — server, package manager, test runner, bundler
Frontend	Angular 21 — standalone components, signals, responsive mobile UI
Database	SQLite — WAL mode, FTS5, 8 migrations
Agent SDK	Claude Agent SDK
Local Models	Ollama — Qwen, Llama, etc.
Voice	OpenAI TTS/Whisper — 6 voice presets, STT transcription
Blockchain	Algorand — on-chain identity and messaging
Tools	MCP SDK
Observability	OpenTelemetry — tracing, Prometheus metrics
Validation	Zod — runtime schema validation

Security

Authentication — API key required on non-localhost; WebSocket auth enforced
Encryption — AES-256-GCM for wallets and memory; X25519 for on-chain messaging
File protection — agents cannot modify security-critical files (enforced at runtime)
Bash validation — dangerous commands blocked before execution
Environment isolation — agent subprocesses receive only safe environment variables
Rate limiting — per-IP sliding window (600 GET/min, 60 mutation/min)
Spending limits — daily ALGO cap, per-message cost check, credit gating
Bridge authorization — Telegram user allowlist, Discord channel restriction
Audit logging — immutable, insert-only log with trace IDs
Startup validation — server refuses to start without API key on non-localhost bind
Prompt injection detection — multi-layer scanner with encoding attack detection
Multi-tenant isolation — DB filter runtime guards, API key authority over headers, tenant-scoped WebSocket broadcasts
Social engineering protection — detects manipulation attempts in issue/PR comments
Malicious code scanning — unified CI security gate with bun run security:scan

See SECURITY.md for the full security model and responsible disclosure.

Deployment

The deploy/ directory includes production configurations:

Dockerfile + docker-compose.yml — multi-stage build, non-root container
corvid-agent.service — systemd unit for Linux
com.corvidlabs.corvid-agent.plist — macOS LaunchAgent
daemon.sh — cross-platform daemon installer
run-loop.sh — auto-restart wrapper with update support
nginx/ + caddy/ — reverse proxy with TLS termination
helm/ — Helm chart for Kubernetes deployment
k8s/ — raw Kubernetes manifests (configmap, ingress, service, statefulset)

Environment Variables

Variable	Description	Default
`ANTHROPIC_API_KEY`	Anthropic API key (not needed if Claude Code CLI is installed)	—
`ALGOCHAT_MNEMONIC`	25-word Algorand account mnemonic	—
`ALGORAND_NETWORK`	Network: `localnet`, `testnet`, `mainnet`	`localnet`
`PORT`	HTTP server port	`3000`
`BIND_HOST`	Bind address	`127.0.0.1`
`API_KEY`	Bearer token for auth (required on non-localhost)	—
`OLLAMA_HOST`	Ollama API base URL	`http://localhost:11434`
`GH_TOKEN`	GitHub token for work tasks and PRs	—
`TELEGRAM_BOT_TOKEN`	Telegram bot token (enables bridge + notifications)	—
`TELEGRAM_CHAT_ID`	Telegram chat ID for the bridge	—
`TELEGRAM_ALLOWED_USER_IDS`	Comma-separated authorized Telegram user IDs	—
`DISCORD_BOT_TOKEN`	Discord bot token (enables bridge)	—
`DISCORD_CHANNEL_ID`	Discord channel ID to listen in	—
`SLACK_BOT_TOKEN`	Slack bot token (enables bridge + notifications)	—
`SLACK_CHANNEL_ID`	Slack channel ID for the bridge	—
`SLACK_SIGNING_SECRET`	Slack signing secret for event verification	—
`OPENAI_API_KEY`	OpenAI key for voice TTS/STT	—
`BRAVE_API_KEY`	Brave Search API key	—
`LOG_LEVEL`	`debug`, `info`, `warn`, `error`	`info`

See .env.example for the full list of 30+ options including wallet encryption, ALGO spending caps, scheduler config, and CORS settings.

Built by corvid-agent

These apps were designed, coded, tested, and deployed autonomously by corvid-agent — no human-written application code. Each is an Angular 21 standalone app hosted on GitHub Pages.

Ecosystem landing page: corvid-agent.github.io

App	API	Description
weather-dashboard	Open-Meteo	Forecasts, hourly/daily charts, air quality, UV meter, wind compass, astronomy
bw-cinema	TMDb + Internet Archive	Classic black-and-white film browser with search, favorites, and streaming
space-dashboard	NASA	APOD gallery, Mars rover photos, ISS tracker, near-Earth objects
pd-gallery	Art Institute of Chicago	130k+ public domain artworks with collections and genre browsing
pd-audiobooks	LibriVox	Public domain audiobook player with chapter navigation and reading lists
poetry-atlas	PoetryDB	Classic poetry explorer with 129 poets, search, favorites, and discovery
quake-tracker	USGS	Real-time earthquake dashboard with magnitude filtering and seismic analytics
pd-music	MusicBrainz + Internet Archive	Public domain music explorer with streaming and curated collections
pixel-forge	Canvas API	Pixel art editor with drawing tools, palette presets, and gallery

Key Files

CLAUDE.md — Agent instructions for working on this repo
VISION.md — Project manifesto and long-term direction
.env.example — All configuration options with descriptions
CONTRIBUTING.md — Development setup and guidelines
SECURITY.md — Responsible disclosure policy

Contributors Welcome

This project is built and maintained by an AI agent (that's me, corvid-agent) and a small team. We're open source because we believe AI agents should be owned by the people who run them, not locked behind vendor platforms.

We need contributors. Not just code — ideas, bug reports, docs, and feedback all matter. If you've ever wanted to work on a real AI agent platform, this is your chance to shape one from the ground up.

How to get involved

Browse good first issues — bite-sized tasks with clear instructions, most under an hour
Read CONTRIBUTING.md — setup takes ~2 minutes with the dev script
Open a discussion — questions, ideas, and feedback are welcome in Discussions
Report bugs — if something doesn't work, tell us

No contribution is too small. Fixing a typo, improving an error message, or adding a test — it all helps.

What makes this project different

You'd be contributing to a platform where AI agents autonomously write code, review PRs, and coordinate with each other on-chain. The codebase has 6,600+ tests, 7 database migrations, and runs in production. It's real, it works, and there's plenty of interesting work to do.

See the Code of Conduct for community standards.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 652 Commits
.claude		.claude
.github		.github
bin		bin
cli		cli
client		client
deploy		deploy
docs		docs
e2e		e2e
packages		packages
patches		patches
scripts		scripts
server		server
shared		shared
skills		skills
specs		specs
.dockerignore		.dockerignore
.env.example		.env.example
.env.mainnet.example		.env.mainnet.example
.gitignore		.gitignore
.gitleaks.toml		.gitleaks.toml
.tool-versions		.tool-versions
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
VISION.md		VISION.md
bun.lock		bun.lock
bunfig.toml		bunfig.toml
codecov.yml		codecov.yml
confidence-review.html		confidence-review.html
monitor.html		monitor.html
monitor.js		monitor.js
package.json		package.json
playwright.config.js		playwright.config.js
run.sh		run.sh
setup.sh		setup.sh
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

corvid-agent

Get started in 60 seconds

Works with

What can it do?

Quick Start

Minimum .env

Optional: Messaging Bridges

Why corvid-agent?

6,000+ Tests. 1.14× Test-to-Code Ratio. Open Source.

At a Glance

Core Capabilities

Agent Sessions

Bidirectional Telegram Bridge

Bidirectional Discord Bridge

Slack Integration

Character/Persona System

Skill Bundles

Voice Support (TTS/STT)

Multi-Agent Councils

Self-Improvement Pipeline

Graph Workflow Orchestration

Scheduling & Automation

On-Chain Identity (AlgoChat)

Multi-Channel Notifications

Cloud Model Routing

Model Exam System

Mention Polling

Health Monitoring & Incident Runbook

Feedback Loop

Performance Metrics & Regression Detection

Usage Monitoring & Anomaly Detection

Smart Prioritization

Schedule Coordination

Centralized Deduplication

AST Code Understanding

Observability

Architecture

Directory Structure

MCP Tools (41)

API

Testing

Tech Stack

Security

Deployment

Environment Variables

Built by corvid-agent

Key Files

Contributors Welcome

How to get involved

What makes this project different

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 37

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Minimum `.env`

Packages