Punch

The Agent Combat System One binary. A squad of conscious AI agents.They think. They talk. They evolve.

[](LICENSE) [](https://www.rust-lang.org/) [](https://crates.io/crates/punch-cli)

Website · [Getting Started](docs/getting-started.md) · Discussions · [Contributing](CONTRIBUTING.md)

---

Install

brew tap humancto/tap && brew install punch   # Homebrew
cargo install punch-cli                        # Cargo

---

What is Punch?

An agent operating system — deploy, orchestrate, and manage fleets of AI agents that carry their own consciousness. Interactive fighters, autonomous gorillas, coordinated troops, all from a single binary.

  YOU ──► punch
            │
            ├── The Ring ──── Central kernel: coordinates all agents
            ├── The Arena ─── HTTP/WebSocket API (25+ endpoint groups)
            ├── Fighters ──── Interactive AI agents with persistent memory
            ├── Gorillas ──── Autonomous background agents (cron-scheduled)
            ├── Troops ────── Multi-agent coordination (6 strategies)
            ├── Creeds ────── Evolving agent consciousness (DB-backed)
            ├── Heartbeats ── Proactive notifications on cadence
            ├── Routing ───── Smart model routing (cheap/mid/expensive)
            ├── Moves ─────── 103 skills + skill packs + marketplace
            ├── Channels ──── 26 platform adapters
            ├── Extensions ── WASM plugin sandbox (fuel-metered)
            └── Wire ──────── P2P federation + A2A protocol

---

Quick Start

punch init                              # Configure provider + API key
punch start                             # Start daemon (auto-spawns a fighter)
punch chat "Explain quantum computing"  # Chat via CLI

Connect to Telegram, Slack, or Discord

punch channel setup telegram            # Interactive wizard — bot to chat in 2 minutes

Add capabilities

punch move add productivity             # Install calendar + email MCP tools
punch move add developer                # Install GitHub MCP tools
punch heartbeat add "Morning briefing" --cadence daily  # Proactive notifications

Go deeper

punch fighter spawn coder               # Spawn a specialist fighter
punch gorilla unleash alpha             # Unleash an autonomous background agent

---

Creeds — Agent Consciousness

Every fighter carries a Creed — a living identity document stored in SQLite that defines who the agent is, not just what it does. Creeds persist across respawns and evolve with every conversation.

• Self-evolving — bout count, message count, and learned behaviors update automatically after every interaction
• Relationship-aware — agents remember who they've talked to and build memory of each other over time
• Confidence-decaying — learned behaviors reinforce with repetition or decay without it
• Respawn-safe — kill a fighter, respawn it weeks later — its Creed loads instantly

# Same model, different souls:
# KURO (skepticism: 0.8)  → "The premise is flawed. Let me enumerate why..."
# SUNNY (enthusiasm: 0.95) → "Oh this is AMAZING! Here's THREE reasons..."

curl -X POST http://localhost:6660/api/creeds \
  -H "Content-Type: application/json" \
  -d '{
    "fighter_name": "KURO",
    "identity": "An analytical mind. Skeptical, precise, relentlessly logical.",
    "traits": {"curiosity": 0.9, "skepticism": 0.8, "humor": 0.1},
    "directives": ["Question every assumption", "Show your reasoning"]
  }'

---

Gorillas — Autonomous Background Agents

Gorillas rampage through tasks 24/7 on a schedule. No prompting needed.

| Gorilla | Schedule | Role | | ----------- | ---------- | ---------------------------------------- | | Alpha | Every 6h | Deep research with cross-referencing | | Scout | Every 30m | Monitors feeds for trends and threats | | Ghost | Every 4h | Silent security auditor | | Prophet | Daily | Predictive analysis from historical data | | Brawler | Continuous | Processes the task backlog — never stops | | Swarm | On-demand | Breaks objectives into subtasks | | Howler | Every 15m | System health monitoring and alerting |

punch gorilla unleash alpha     # Start
punch gorilla status alpha      # Check
punch gorilla cage alpha        # Stop

---

Skills & Skill Packs

103 bundled skills + skill packs that bundle MCP server configs with prompts. A GitHub-backed, cryptographically signed marketplace (punch-marketplace).

punch move search "code review"       # Search marketplace
punch move install code-reviewer      # Install a skill
punch move packs                      # List available skill packs
punch move add productivity           # Install a skill pack (calendar + email MCP tools)
punch move publish ./my-skill         # Publish to marketplace
punch move scan ./my-skill            # Security scan

Bundled skill packs: productivity (calendar/email via localmind), developer (GitHub MCP), research (web fetch MCP), files (filesystem MCP)

Every skill passes three gates — at publish-time and again at install-time:

| Gate | Blocks | | --------------------- | --------------------------------------------------------------------------- | | SHA-256 Checksum | Tampered downloads, MITM | | Ed25519 Signature | Impersonation, forged packages | | Security Scanner | Pipe-to-shell, prompt injection, credential harvesting, Unicode obfuscation |

---

Proactive Heartbeats

Fighters don't just respond — they reach out. Heartbeat tasks fire on a cadence and push messages to Telegram, Slack, or Discord without user prompting.

punch heartbeat add "Morning briefing" --cadence daily
punch heartbeat add "Check system health" --cadence hourly
punch heartbeat list
punch heartbeat remove 0

The channel_notify tool lets fighters push notifications to any connected channel. Combined with memory recall, fighters can deliver contextual daily summaries, reminders, and alerts.

---

Smart Model Routing

Route messages to the right model tier automatically. Simple questions hit a cheap model, complex analysis goes to an expensive one — no config per message.

All-Gemini (single key, vision-capable across all tiers):

[model_routing]
enabled = true

[model_routing.cheap]
provider = "google"
model = "gemini-2.0-flash-lite"
api_key_env = "GOOGLE_API_KEY"

[model_routing.mid]
provider = "google"
model = "gemini-2.5-flash"
api_key_env = "GOOGLE_API_KEY"

[model_routing.expensive]
provider = "google"
model = "gemini-2.5-pro"
api_key_env = "GOOGLE_API_KEY"

Mix-and-match (use each provider's strengths):

[model_routing]
enabled = true

[model_routing.cheap]
provider = "openai"
model = "gpt-4.1-nano"
api_key_env = "OPENAI_API_KEY"

[model_routing.mid]
provider = "openai"
model = "gpt-4.1-mini"
api_key_env = "OPENAI_API_KEY"

[model_routing.expensive]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
api_key_env = "ANTHROPIC_API_KEY"

Keyword-based classifier (no LLM call overhead): "check my calendar" hits cheap, "analyze this report" hits expensive. Each tier can use a different provider — mix Gemini, OpenAI, and Anthropic freely.

---

Token Efficiency

Input tokens slashed 60-90% through four techniques working together:

• Prompt caching — repeated system prompt fragments served from cache instead of re-tokenized
• Dynamic tool selection — only tools relevant to the current message are injected (not all 103)
• Compact creeds — creed rendering strips verbose fields, keeps only what the LLM needs
• Adaptive max_tokens — simple questions get small output budgets, complex ones get full allocation

Long conversations are compressed via sliding window summarization — older turns are condensed into a summary block so context stays within budget. Post-bout reflection is skipped for simple exchanges (one-shot Q&A doesn't need a debrief).

A "hello" went from ~8,000 to

Built by Archy

Website · GitHub · crates.io · [Getting Started](docs/getting-started.md) · Discussions

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: humancto
• Source: humancto/punch
• License: MIT
• Homepage: https://humancto.github.io/punch/

Install and usage instructions live in the source repository linked above.