https://github.com/cgcardona/agentception
AgentCeption — multi-agent orchestration system for AI-powered development workflows
https://github.com/cgcardona/agentception
agents ai fastapi orchestration python
Last synced: 3 months ago
JSON representation
AgentCeption — multi-agent orchestration system for AI-powered development workflows
- Host: GitHub
- URL: https://github.com/cgcardona/agentception
- Owner: cgcardona
- License: mit
- Created: 2026-03-04T15:52:56.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-11T23:57:25.000Z (4 months ago)
- Last Synced: 2026-03-11T23:57:35.334Z (4 months ago)
- Topics: agents, ai, fastapi, orchestration, python
- Language: Python
- Size: 5.2 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# AgentCeption
[](https://github.com/cgcardona/agentception/actions/workflows/ci.yml)
[](LICENSE)
> *The infinite machine behind the machines.*
For all of recorded history, human progress has been constrained by one thing: the number of hours in a day multiplied by the number of people willing to work. We called it scarcity, and we built entire economic systems around managing it.
Then something changed.
Autonomous AI agents can now reason, plan, write code, open pull requests, and report back. The singularity isn't near. **It's here.** When agents can carry the full cognitive load of an org — planning, dependency modeling, implementation, review — humans get to operate at the level of ideas. We are moving from a world of scarcity into a world of **superabundance**.
AgentCeption is a bet on that future.
```
Brain dump → Structured plan → GitHub issues → Agent org tree → PRs → Merged
```
One input. Zero boilerplate. The work happens.
---
## How It Works
### Step 1 — Plan
Paste anything. The LLM converts it into a `PlanSpec`: phases, issues, dependencies, acceptance criteria.
### Step 2 — Review
The YAML opens in an editor. Adjust anything. Click **Create Issues** to file everything on GitHub.
### Step 3 — Design the org
Configure the agent hierarchy before launching. Each node is either a **Coordinator** (surveys scope, assembles a team) or a **Worker** (does the work directly). Assign roles and cognitive architecture figures to each node, save a preset, or start from the default CEO → CTO → Engineering Manager / QA Lead → developer / reviewer tree.
### Step 4 — Ship
Click **Launch** on an unlocked phase. The org tree springs to life: coordinators cascade work down to engineers, each operating in an isolated git worktree. PRs appear. Phases unlock. You watch.
Every agent has a **cognitive architecture** — a composed identity (historical thinkers + archetypes + skill domains + behavioral atoms) injected into its context. You are deploying *reasoners*, not LLM calls. This is the infrastructure for deploying **judgment at scale**.
Most AI coding tools are power tools. They make individual developers faster. AgentCeption is not a power tool. It is a **force multiplier on the organizational unit itself** — what would a brilliant 10-person team look like if the team had no size limit? The creative renaissance that has always been one good team away is now one brain dump away.
---
## Quick Start
### Option A — Cloud (Anthropic)
```bash
git clone https://github.com/cgcardona/agentception
cd agentception
cp .env.example .env
# Set ANTHROPIC_API_KEY, GITHUB_TOKEN, GH_REPO, HOST_WORKTREES_DIR
docker compose up -d
docker compose exec agentception alembic upgrade head
open http://localhost:1337
```
### Option B — Local models (free, private)
Run agents entirely on your own hardware with [Ollama](https://ollama.com). No API key, no cloud, no usage bill. Works on **macOS, Linux, and Windows** — GPU-accelerated on Apple Silicon (Metal), NVIDIA (CUDA), and AMD (ROCm).
```bash
# 1. Install Ollama — https://ollama.com/download
# macOS: brew install ollama && brew services start ollama
# Linux: curl -fsSL https://ollama.com/install.sh | sh
# Windows: download the installer from https://ollama.com/download
# Pull a model
ollama pull qwen2.5-coder:7b # fast, good quality (~4 GB)
# ollama pull qwen2.5-coder:32b # better quality, needs 16 GB+ RAM
# 2. Clone and configure
git clone https://github.com/cgcardona/agentception
cd agentception
cp .env.example .env
```
Then set in `.env`:
```bash
LLM_PROVIDER=local
LOCAL_LLM_BASE_URL=http://host.docker.internal:11434
LOCAL_LLM_MODEL=qwen2.5-coder:7b
GITHUB_TOKEN=ghp_...
GH_REPO=owner/repo
HOST_WORKTREES_DIR=/path/to/worktrees
```
```bash
# 3. Start
docker compose up -d
docker compose exec agentception alembic upgrade head
# macOS: open http://localhost:1337
# Linux/Windows: navigate to http://localhost:1337
```
> **Performance tip:** Set `WORKTREE_INDEX_ENABLED=false` in `.env` to skip per-agent code indexing (saves ~2 GB RSS and significant CPU) when running on constrained hardware.
See [docs/guides/local-llm.md](docs/guides/local-llm.md) for the full Ollama setup guide and model recommendations.
---
## Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| `GITHUB_TOKEN` | ✅ | GitHub PAT with `repo` + `issues` scope |
| `GH_REPO` | ✅ | Repo this instance manages — `owner/repo` |
| `HOST_WORKTREES_DIR` | ✅ | Host path where agent worktrees are created |
| `DATABASE_URL` | ✅ | PostgreSQL connection string (default in `docker-compose.yml`) |
| `LLM_PROVIDER` | — | `anthropic` (default) or `local` |
| `ANTHROPIC_API_KEY` | Cloud only | Required when `LLM_PROVIDER=anthropic` |
| `LOCAL_LLM_BASE_URL` | Local only | Ollama base URL, e.g. `http://host.docker.internal:11434` |
| `LOCAL_LLM_MODEL` | Local only | Model tag, e.g. `qwen2.5-coder:7b` |
| `WORKTREE_INDEX_ENABLED` | — | `true`/`false` — enable per-agent code search (default `false`) |
See [docs/guides/setup.md](docs/guides/setup.md) for the full first-run walkthrough.
> **Security note:** By default all `/api/*` endpoints are unauthenticated. If your machine is on a shared network (office LAN, cloud VM, dev box), set `AC_API_KEY` in `.env` before starting. Without it, anyone who can reach port 1337 can dispatch agents and burn your Anthropic credits. Generate a key with `openssl rand -hex 32`.
---
## MCP Integration
AgentCeption exposes an MCP server that any MCP-compatible client can use:
```json
{
"mcpServers": {
"agentception": {
"command": "docker",
"args": ["compose", "-f", "/path/to/agentception/docker-compose.yml",
"exec", "-T", "agentception", "python", "-m", "agentception.mcp.stdio_server"]
}
}
}
```
See [docs/guides/integrate.md](docs/guides/integrate.md) for the full tool reference.
---
## Documentation
| Guide | What it covers |
|-------|----------------|
| [Setup](docs/guides/setup.md) | First-run, Docker, environment variables |
| [Local LLM / Ollama](docs/guides/local-llm.md) | Running agents on local hardware with Ollama (macOS, Linux, Windows) |
| [Local LLM Scaling](docs/guides/local-llm-scaling.md) | Multi-agent concurrency and LiteLLM proxy |
| [MCP Integration](docs/guides/integrate.md) | MCP client tool integration |
| [Dispatching Agents](docs/guides/dispatch.md) | How to launch, monitor, and cancel agent runs |
| [Developer Workflow](docs/guides/developer-workflow.md) | Bind mounts, mypy, tests, build pipeline |
| [Contributing](docs/guides/contributing.md) | Branch conventions, PR process, commit style |
| Reference | What it covers |
|-----------|----------------|
| [API Routes](docs/reference/api.md) | Every HTTP endpoint — semantic URL taxonomy |
| [Cognitive Architecture](docs/reference/cognitive-arch.md) | Figures, archetypes, skill domains, atoms |
| [Type Contracts](docs/reference/type-contracts.md) | Pydantic models, TypedDicts, layer contracts |
---
## Stack
Python 3.12 · FastAPI · Jinja2 · HTMX · Alpine.js · SCSS · Pydantic v2 · SQLAlchemy (async) · Alembic · PostgreSQL · Qdrant
**LLM backends:** Anthropic (`claude-sonnet-4-6`, `claude-opus-4-6`) or any [Ollama](https://ollama.com)-compatible local model. Switch with a single env var — no code changes required.
---
## License
MIT