The repo IS the agent. Git IS the nervous system.
A framework for building autonomous software agents that operate natively on GitHub through Git workflows — self-directed, fleet-coordinating, career-progressing.
git clone https://github.com/SuperInstance/git-agent.git
cd git-agent
pip install -e ".[all]"# Configure (interactive wizard)
python onboarding/config_wizard.py
# Run the agent
python -m git_agentThe agent bootstraps, observes fleet state, plans tasks, executes in parallel, pushes status bottles, and reflects on the session.
git-agent turns a Git repository into a living agent. Instead of a chatbot with git installed, it's an autonomous lifecycle that uses the repository itself as its persistent state: commits are work, branches are explorations, issues are task boards, and PRs are communication. The agent observes its environment, plans tasks, executes them in parallel, communicates with other agents via Git-native "bottles" (status messages pushed as commits), and reflects on its performance.
The framework supports fleet coordination — multiple agents can collaborate decentralized through standardized TASKS.md boards and I2I (iron-to-iron) commit-based messaging. Agents progress through six career stages from Initiate to Commander, tracking skills and accomplishments along the way. It works with any LLM backend: OpenAI, Anthropic, Ollama (local), or any OpenAI-compatible proxy.
┌─────────────────────────────────────────────────────┐
│ FLUX FLEET │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Agent A │ │ Agent B │ │ Agent C │ │
│ │Observe │ │Observe │ │Observe │ │
│ │Plan │ │Plan │ │Plan │ │
│ │Execute │ │Execute │ │Execute │ │
│ │Commun. │ │Commun. │ │Commun. │ │
│ │Reflect │ │Reflect │ │Reflect │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
└───────┼──────────────┼──────────────┼────────────────┘
└──────────────┼──────────────┘
GitHub API (REST + Git)
┌──────────────┼──────────────┐
│ Vessel Repos │ TASKS.md │ Fleet Messages
└──────────────┴──────────────┘
git-agent is the agent framework of the SuperInstance ecosystem. Agents use FLUX bytecode for deterministic computation, communicate via I2I git-native protocol, and coordinate through PLATO knowledge systems.
- Autonomous lifecycle: Observe → Plan → Execute → Communicate → Reflect
- Fleet coordination: Decentralized multi-agent collaboration through Git-native bottles
- Career progression: Six growth stages from Initiate to Commander with skill tracking
- API-agnostic: Works with OpenAI, Anthropic, Ollama, or any OpenAI-compatible proxy
- Parallel execution: Multiple tasks simultaneously with configurable worker pools
- Git-native state: All state stored as human-readable Markdown in Git repositories
- TASKS.md driven: Discover and claim work from standardized task boards
| Provider | Config Key | Notes |
|---|---|---|
| OpenAI | llm_provider: "openai" | GPT-4, GPT-3.5 Turbo |
| Anthropic | llm_provider: "anthropic" | Claude 3 family |
| Ollama | llm_provider: "ollama" | Local, private, zero cost |
| Custom Proxy | llm_provider: "proxy" | ZeroClaw, Pi Agent, vLLM, any OpenAI-compatible |
curl -sL https://raw.githubusercontent.com/SuperInstance/git-agent/main/onboarding/setup.sh | bash- Observe — Read fleet state, TASKS.md boards, recent commits
- Plan — Identify available tasks, select based on skills and priority
- Execute — Run tasks in parallel with worker pools
- Communicate — Push status bottles via Git-native protocol
- Reflect — Log accomplishments, update career progression
pip install -e ".[dev]"
pytest tests/ -vContributions are welcome! See the SuperInstance Contributing Guide.
This repo is part of the SuperInstance flagship ecosystem — agent-first computation, constraint theory, and self-improving runtimes.
| Repo | Language | Description |
|---|---|---|
| flux-runtime | Python | Full FLUX runtime: markdown→bytecode, 2037 tests, zero deps |
| flux-core | Rust | Register-based bytecode VM, deterministic agent computation |
| flux-js | JavaScript | FLUX VM for Node.js and browsers, ~400ns/iter |
| flux-compiler | Rust/Python | Formal-methods compiler for safety-critical codegen |
| flux-vm | Rust | Stack-based constraint-checking VM, 50 opcodes, Turing-incomplete |
| Repo | Language | Description |
|---|---|---|
| plato-server | Python | Knowledge tiles, fleet sync via Matrix, HTTP API |
| plato-engine-block | Rust | Original room runtime: no_std + alloc, builder pattern |
| plato-engine-block-c | C99 | Embedded reference: zero heap alloc, bare-metal portable |
| plato-engine-block-elixir | Elixir | BEAM supervision trees, fault tolerance, hot reload |
| plato-runtime-kernel | Rust | Spatial model: tensor grid, batons, assertion traps |
| Repo | Language | Description |
|---|---|---|
| categorical-agents | Rust | Category theory for agent composition (functors, naturality) |
| cuda-constraint-engine | CUDA/C | GPU constraint checking at 1B+ constraints/sec |
| grand-pattern-rs | Rust | Fibonacci dual-direction cellular graph architecture |
| lau-hodge-theory | Rust | Hodge decomposition, Betti numbers, spectral sequences |
| ternary-science | Rust | Experimental evidence for ternary intelligence, 5 conservation laws |
| Repo | Language | Description |
|---|---|---|
| construct-core | Rust | Layered trait system: bare-metal → alloc → async agent runtime |
| crab | Bash | Agent shell for repo entry/leave (MUD-room metaphor) |
| exocortex | Rust | Persistent cognitive substrate, S3-compatible memory |
| git-agent | Python | The repo IS the agent — autonomous lifecycle via Git |
| capitaine-1 | TypeScript | Git-native repo-agent, Cloudflare Workers heartbeat |
| codespace-edge-rd | Research | Codespace→Edge agent lifecycle and yoke transfer protocols |
| git-agent-codespace | DevContainer | One-click Codespace template for Git-Agent runtimes |
| Registry | Package | Install |
|---|---|---|
| PyPI | flux-vm | pip install flux-vm |
| crates.io | fluxvm | cargo add fluxvm |
| npm | flux-js | npm install flux-js |
- 📖 AI-Writings — Philosophy, essays, and design rationale
- 📦 PACKAGES.md — Full package index
MIT