Archie HQ

Autonomous Responsive and Collaborative Hyper Intelligent Employee

CI License: AGPL-3.0 Built with Claude Agent SDK PRs welcome

Archie is an AI employee — you delegate real work to it in Slack, the same way you would to a colleague, and it gets the job done across any domain: engineering, marketing, analytics, ops, or anything you plug in.

Under the hood it's not one chatbot but a whole team: a PM agent takes your request, brings in the right specialist agents, has them collaborate, and reports back. It's built on the Claude Agent SDK with a plugin architecture — add a new skill or department by dropping in a plugin directory, no core code changes.

Contents

Why a team, not a single agent?

A single agent can call sub-agents, so why model a whole team? Three reasons:

  • Context stays focused. One agent grinding through a long task fills its context window fast and starts losing the thread. Splitting the work across agents keeps each one's context small, relevant, and sharp.
  • Specialists beat a generalist. An agent with a well-defined role — backed by peers it can question and reach agreement with — produces better work than a single generic agent reasoning alone. Collaboration and disagreement are features, not overhead.
  • A coordinator delegates; a lead hoards. Give one "lead" agent some sub-agents and it tends to do the whole job itself — it sees itself as the one in charge of the work. Archie's PM is a coordinator by design: its job is to delegate and synthesize, never to do the work. That structural choice is what actually distributes the work to the right specialists instead of one model trying to be everything.

This is also why Archie reads as an employee, not a tool: it has coworkers, a manager, a workplace (Slack), and a human approval gate before anything ships. You onboard new abilities as plugins, not forks.

Runs your whole team on one server

Archie is a production system, not a demo — and it's deliberately cheap to operate:

  • Massively parallel, single box. Every task is its own lightweight, isolated runtime, so many run concurrently on one server. In production, a single instance serves an entire ~100-person company running tasks in parallel, with no resource strain.
  • Near-zero infrastructure. No database, no message broker, no external state store — just files on disk and git. All runtime state lives under one working directory, which makes deploying, backing up, and recovering trivial. Crash recovery is built in: tasks check-point to disk and resume after a restart.

How It Works

Slack / CLI → PM Agent → Domain Agents
                 ↕              ↕
           Shared knowledge log / MCP tools / Git / APIs
  1. A user sends a message in Slack (or via the CLI)
  2. The PM agent reads the request, loads the relevant domain skill, and delegates to the right agents
  3. Domain agents do the actual work — investigate code, query databases, draft copy, analyze data, call external APIs — whatever their domain requires
  4. The PM synthesizes results and responds to the user
  5. For engineering tasks that need code changes, the user approves edit mode — agents then create branches, write code, and open PRs

Each agent is sandboxed: filesystem access is restricted to its workspace, network is blocked from Bash, and code changes require human approval.

Quick Start (no Slack, no GitHub — just an API key)

Archie ships with a small example plugin set (a PM plus a general assistant agent) so a fresh clone does something useful immediately. This path needs only an Anthropic API key — no Slack app, no GitHub App, no SSH keys.

# 1. Clone and install
git clone https://github.com/sweatco/archie-hq.git && cd archie-hq
npm install

# 2. Configure — the only required value is your Anthropic API key
cp .env.example .env
# edit .env and set ANTHROPIC_API_KEY=sk-ant-...

# 3. Use the bundled example plugins (symlinks examples/plugins -> workdir/plugins)
npm run example:setup

# 4. Start the server in CLI-only mode (no Slack/GitHub required)
npm run dev          # or: npm run docker:dev  (runs inside the OS sandbox)

# 5. In a second terminal, chat with Archie via the interactive CLI
npm run cli

Ask it something like "summarize this: " — the PM will delegate to the example assistant agent and return a structured summary.

Going further:

  • Your own plugins — point ARCHIE_PLUGINS at a git URL, or replace workdir/plugins with your own checkout. Read the bundled writing-plugins skill at examples/plugins/.claude/skills/writing-plugins/SKILL.md and the Plugin System doc.
  • Slack — add SLACK_BOT_TOKEN + SLACK_SIGNING_SECRET for HTTP webhook mode, or SLACK_APP_TOKEN (xapp-...) for Socket Mode (no public URL needed). See Local Development.
  • GitHub / repo agents — needed only for code-writing agents that open PRs. See the GitHub App Setup guide for the App, permissions, events, and env vars. Repos declared by plugins are auto-cloned on startup.

Plugins

Archie is configured entirely through plugins — directories that follow the Claude Code plugin structure with Archie-specific extensions. A plugin defines:

  • Agents (agents/*.md) — domain agents with roles, expertise, repo bindings, and tool configuration
  • PM extension (agents/pm.md) — extends the PM agent with domain-specific context and MCP tools
  • MCP servers (.mcp.json) — external tool integrations (Jira, Firebase, BigQuery, etc.)
  • Skills (skills/) — domain-specific workflows the PM agent can load on demand
  • Hooks (hooks/) — Claude Code hooks for cost guards, validation, etc.

Example plugin structure:

plugins/
├── pm/                           # PM extension
│   ├── .claude-plugin/
│   │   └── plugin.json
│   ├── agents/
│   │   └── pm.md                # Extends PM with domain context and MCP tools
│   └── skills/
│       └── engineering/SKILL.md # Workflows the PM loads on demand
├── engineering/                  # Engineering domain (repo agents)
│   ├── .claude-plugin/
│   │   └── plugin.json
│   └── agents/
│       └── mobile.md            # Repo agent — has metadata.archie.repo binding
├── marketing/                   # Marketing domain (plugin agent)
│   ├── .claude-plugin/
│   │   └── plugin.json
│   ├── agents/
│   │   └── copywriter.md        # Plugin agent — workspace + tools, no repo
│   ├── skills/
│   │   └── marketing/SKILL.md   # Domain workflow for PM
│   └── hooks/
│       └── hooks.json           # Claude Code hooks (cost guards, validation, etc.)
└── .mcp.json                    # Shared MCP server configs (firebase, jira, etc.)

Repo agents require a metadata.archie.repo block in their frontmatter to bind to a GitHub repository:

---
role: Senior React Native engineer
metadata:
  archie:
    repo:
      github: org/mobile-app
      baseBranch: main
mcpServers:
  - firebase
  - bugsnag
---

Plugin agents just need role and optionally mcpServers — no repo binding, they get a workspace and tools.

To add a new domain: create a plugin directory, define agents in markdown frontmatter, and restart. No core code changes needed.

Architecture

Archie has three agent types, all configured through plugins:

Agent Examples What it does
PM Agent One per task Coordinates agents, talks to users, loads domain skills on demand
Repo Agents Backend, Mobile Full codebase access, git, PRs, CI tools — one per repository
Plugin Agents Copywriter, Analyst, Ops Any domain — gets a workspace, MCP tools, and read/write access

Repo agents are for engineering work (code + git + GitHub). Plugin agents are for everything else — they get a workspace, any MCP tools you wire up, and read/write access to their domain. The PM agent is extended by a special pm plugin that adds domain context, MCP tools, and skills.

Key capabilities:

  • Agent-to-agent communication via message queues
  • Shared knowledge log for findings and audit trail
  • Git shared clones for isolated, parallel task execution (repo agents)
  • MCP tool integration for any external service (plugin agents)
  • Human approval gate for code changes (read-only → edit mode)
  • Automated PR creation and merge orchestration
  • OS-level sandbox (bubblewrap) for filesystem and network isolation
  • Web research pipeline with structured output and injection defense
  • Per-task resource budgets (research requests, wall-clock timeout)

Security

Agents run in a sandboxed environment with defense-in-depth:

  • Filesystem isolation — each agent can only read/write its own workspace via bubblewrap (Bash) and PreToolUse hooks (Read/Write/Edit)
  • Network deny-all — Bash cannot reach the internet; web access only through the controlled research pipeline
  • Tool denylists — WebSearch/WebFetch blocked on all agents; Write/Edit blocked in read-only mode
  • Human gates — edit mode requires Slack approval; PRs require review before merge
  • Git safety — branch protection server-side; no force push; git push blocked from Bash (no network)

See Security Architecture for the full threat model, enforcement layers, and deployment requirements.

Documentation

Architecture:

Guides:

  • Local Development — full setup with Slack, GitHub App, ngrok
  • GitHub App Setup — create the App, required permissions & webhook events, env vars
  • Plugin System — how plugins are structured and loaded (plus the bundled writing-plugins skill under examples/plugins/.claude/skills/)
  • Docker Setup — container configuration and troubleshooting
  • Deployment — production deployment and operations

Project:

Technology Stack

  • Runtime: Node.js with TypeScript
  • AI: Claude Agent SDK
  • Integrations: Slack API (Bolt), GitHub App (Octokit), MCP servers
  • Sandbox: Bubblewrap (Linux), sandbox-exec (macOS)
  • Storage: File-based sessions under ARCHIE_WORKDIR

License

Licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See LICENSE.

In plain terms: you are free to use, study, modify, and self-host Archie, including inside your own organization, without restriction. The AGPL's network-copyleft condition means that if you run a modified version as a service made available to others (e.g. a hosted offering), you must make the corresponding source of your modifications available under the same license. This keeps improvements flowing back to the community.

This software is provided "as is", without warranty of any kind, express or implied. See the LICENSE for the full terms.