Two minutes
to your first team.

01 - Summon it

Summon it

Python 3.10 or newer. That is the only thing you need to have already.

# the whole install
pip install AgentGOD

# the whole setup
agentgod

The first run asks for your Anthropic key - typing hidden, probed against the API when a person is present, written to a .env inside the AgentGod data directory. It never asks twice.

Prefer doing it by hand? pip install -r requirements.txt, copy .env.example to .env, and paste a key from console.anthropic.com. A real environment variable outranks the file, so CI can inject ANTHROPIC_API_KEY without one.

02 - First contact

First contact

Give it a task. It will not answer you. It will go and build somebody who can - and you get to watch it happen.

agentgod "draft a 200-word investor memo on the
          vector database market"

What happens next

One live board takes over the terminal: which phase is running, every agent on it, and what each one is doing right now - written, reused, running, repairing itself, done, failed. It animates while the machine works and vanishes when it is finished.

  PLAN  ▸  FORGE  ▸  DEPS  ▸  RUN  ▸  MERGE  ▸  CHECK     00:08
  ⠼ run  analysis_agent is working  (2/3)

   ⠼  research_agent   Gather the market facts         reused
   ⠼  analysis_agent   Weigh cost, recall, ops         3s
   ○  memo_writer      Draft the 200-word brief        …

  team   ●  memo_writer      built   2.8s · 61 tok
         ●  research_agent   reused  1.5s · 85 tok
  run    10.4s · 5 LLM calls · 1,395 in / 226 out · ~$0.0003
  saved  runs/20260908_221204_draft-a-200-word.md

  ❯ Keep the 1 new agent (memo_writer) for reuse? [Keep/discard/always]

That last line is the whole philosophy in one prompt. Nothing enters your library without you saying so.

Pipe it, redirect it or run it in CI and the same run comes out as clean aligned plain text - same information, no color, nothing that fights a log file. The answer goes to stdout; everything else goes to stderr, so agentgod "..." > answer.md captures exactly the answer.

03 - What to ask it

What to ask it

Ask it something that splits. A question with one obvious lookup behind it gets one agent and you may as well have asked a chatbot. A question with three angles gets three specialists working at once.

Vague enough and it earns one clarifying question before anything spawns - one, and only when there is a person there to answer it.

04 - The cage

The cage

A system that writes its own workers in a real language and then runs them has one question to answer before any other: what stops the thing it just wrote?

Names are not trusted

Every agent identifier is reduced to a safe token before it goes anywhere near the filesystem. ../../../pwned becomes pwned.

Code is not trusted

Every generated file is parsed and inspected - import by import, call by call - before it is allowed to become a process. The whole standard library is available, minus the thirteen modules that would undo the rest of this list.

subprocess   shutil   socket   pickle   importlib

eval()       exec()   shelling out   writing to disk

Dependencies are not trusted

A package is installed only if it is one of the 81 vetted names, and only into a separate environment - never yours. An invented package name is refused rather than installed: a hallucinated name is a supply-chain vector, not a typo to be helpfully resolved.

Time is not unlimited

Every agent runs against a hard deadline. If it fails, its own error becomes the instruction for rewriting it - twice. Then it is excused, named in the report, and its failure is never passed downstream as though it were a result.

Said plainly: this is static validation, not a sandbox. Treat the task string as a trust boundary and do not paste untrusted text into it. Docker-per-agent is on the roadmap.

05 - The library

It gets cheaper every run

An agent is written once and kept. The next task that needs the same capability gets it back for free - no planning guess, no code generation, no tokens. Only genuinely new capabilities cost anything.

run 1  solar panels       6 LLM calls   built research_agent + summary_agent
run 2  Brazilian coffee   4 LLM calls   both reused, free
run 3  European e-bikes   4 LLM calls   both reused, free

This works because generated agents are topic-agnostic by construction. The generator is forbidden from writing your subject into the agent's prompt - the subject arrives at runtime. The research_agent built for solar panels contains the word “solar” exactly zero times.

And it keeps score on itself

Every reused agent's run is recorded as a win or a loss. One that has failed more tasks than it finished is retired automatically and rebuilt from scratch; a repaired agent advances a generation and starts with a clean record.

/library   the agents kept for reuse, with each one's record
/stats     the lifetime ledger: runs, reuse savings, reliability
/audit     catch any agent that hardcoded its first task
/forget    drop one agent from the library
/history   the recent archived runs, or reopen run n
/last      show the most recent answer again
/where     where your answers, agents and key live on disk

Kept agents live in the AgentGod data directory, which agentgod where prints, ranked by how often they have actually been used. The planner is shown your library before it plans, and told to prefer a name you already own over inventing a new one.

06 - Command line

Command line

agentgod                                  interactive session
agentgod "write a haiku about rain"       one task, then exit
agentgod --json "compare X and Y"         machine-readable, on stdout
echo summarise this repo | agentgod -     task from stdin
agentgod library | stats | history        free, offline, no key
agentgod --discard "one-off experiment"   run without growing the library

Exit codes are a contract: 0 succeeded · 1 failed · 2 bad usage · 130 interrupted.

07 - The dials

The dials

Everything here has a working default. Only the key is required. Set them in .env or the environment.

The live board wants rich, but only wants it - without it every run still works in plain text. Pipes, redirects and CI are detected and get plain text automatically.

08 - Changelog

Changelog

Currently 0.1.2, and early. No test needs an API key, a network connection, or the model to be in a good mood. Interfaces on this page may still change before 1.0. The full history lives in CHANGELOG.md.