A unified CLI ecosystem for agentic development.

Forma is a protocol and ecosystem that standardises CLI tools for consistent behaviour across agentic workflows. Instead of wrestling with different output formats, flag conventions, and error handling patterns for every API, Forma tools follow a single protocol that makes them predictable and composable.

The core insight: AI assistants and power users need tools that behave consistently. When every CLI has its own quirks, automation breaks. Forma solves this by defining a protocol that covers command structure, JSON output shapes, exit codes, authentication patterns, and stream separation. Any tool that follows the protocol becomes instantly usable by both humans and AI.

The ecosystem includes 64 Forma CLIs for popular SaaS APIs, 30 vendor CLIs, 48 system tools, and an MCP server - 143 capabilities across 16 collections, tracked in a central registry. An always-on daemon with a persistent Claude session orchestrates the ecosystem, accumulates knowledge, and is accessible from anywhere via remote control.

Every SaaS API has its own CLI (or none at all). Each one:

• Has different flags (-j vs --json vs --format json)
• Outputs different shapes (arrays, objects, wrapped, raw)
• Uses different exit codes (or just 0/1)
• Mixes progress bars with data in stdout

This chaos breaks agentic workflows where AI assistants need to discover, invoke, and chain tools reliably.

Forma is a protocol + ecosystem + daemon that makes CLI tools:

MCP is powerful, but it has a scaling problem: every registered tool consumes context tokens. With 2-3 MCP servers, you can burn 20% of your context window before you've started working. Try running 10+ tools and you're out of room.

MCP is great for 2-3 frequently-used integrations. Forma is for ecosystems of 10+ tools where context efficiency matters.

• AI Assistants (Claude Code, Codex, Gemini) - Discover and use tools without MCP overhead
• Power Users - Chain tools with jq, build automation scripts
• Developers - Ship CLIs that work in agentic workflows
• Entrepreneurs - Always-on daemon manages tools across workspaces (agencies, clients, personal)

+-----------------------------------------------------------------------------------+
|                        FORMA ECOSYSTEM (143 capabilities)                         |
+-----------------------------------------------------------------------------------+
|                                                                                   |
|  64 Forma CLIs        30 Vendor CLIs        48 System Tools       1 MCP          |
|  +---------+--+--+     +-----+-----+--+     +-----+-----+--+     +-----+        |
|  |xero|harv|..|  |     |gws|gh|wrng|  |     |jq|ffm|pan|  |     |cf-mcp|       |
|  +----+----+--+--+     +---+--+----+--+     +--+---+---+--+     +------+        |
|       |                      |                    |                    |          |
|       +----------+-----------+--------------------+--------------------+          |
|                  |                                                                |
|         +--------v--------+          +---------------------------+               |
|         | FORMA PROTOCOL  |          |     FORMA DAEMON (OS)     |               |
|         |                 |          |                           |               |
|         |  - --json       |          |  Kernel: process monitor  |               |
|         |  - --help       |          |  User space: per-workspace|               |
|         |  - exit codes   |          |    - SOUL.md (identity)   |               |
|         |  - auth pattern |          |    - memory/ (knowledge)  |               |
|         |  - {data, meta} |          |    - journal/ (activity)  |               |
|         |  - --no-cache   |          |    - persistent session   |               |
|         +--------+--------+          |    - schedules + monitors |               |
|                  |                   +-------------+-------------+               |
|    +-------------+-------------+                   |                              |
|    v                           v                   v                              |
|  +------------------+       +------------------+  +------------------+           |
|  |   AI Assistants  |       |   Power Users    |  |  Remote Control  |           |
|  | (Claude/Gemini)  |       |   (Shell/jq)     |  | (Phone/Browser)  |           |
|  +------------------+       +------------------+  +------------------+           |
|                                                                                   |
+-----------------------------------------------------------------------------------+

# What tools are available?
forma list

# What can Xero do?
xero --help

# List draft invoices as JSON
xero invoices list --status DRAFT --json

# Pipe between tools
harvest clients list --json | jq -r '.data[].name' | head -5

# Check auth status
xero auth status --json

An always-on orchestrator that monitors, schedules, and learns across the ecosystem. Follows an OS architecture: shared kernel for process monitoring, isolated user-space daemons per workspace.

• Schedules - Cron-triggered tasks (daily audits, weekly verification, monthly billing)
• Monitors - Condition-triggered reactions (uncommitted changes, credential expiry, registry drift)
• Memory - Accumulates knowledge as flat .md files. Patterns, facts, warnings, preferences. Never decays.
• Journal - Daily activity log with monthly archival
• Persistent Session - The daemon IS a Claude session, not just a spawner. Accumulates context across ticks.
• Remote Control - Drop in from your phone, tablet, or any browser via claude.ai/code

Each workspace gets its own daemon with its own identity, memory, and context. Like separate user accounts on the same OS.

forma daemon --workspace default install       # Personal daemon
forma daemon --workspace evolution7 install     # Agency daemon
forma daemon services                           # See all daemons
forma daemon health                             # Cross-workspace view

forma daemon chat                  # Interactive session with remote control
forma daemon ask "morning briefing"  # Quick context-aware question
forma daemon status                # What's happening
forma daemon journal               # What happened today
forma daemon memory list           # What it's learned

Five specialised agent roles for autonomous tool development:

Scout --> Architect(s) --> Verifier(s) --> Inspector(s)
              ^                |               |
              +-- fix (max 3) -+---------------+

Warden (independent, on-demand registry custodian)

The Forma registry is the central mechanism for tool discovery. 143 tools across 16 collections.

1. Registration: Each tool declares itself in its pyproject.toml with a [tool.forma] section
2. Discovery: Run forma list to see all registered tools
3. Exploration: Run <tool> --help for any tool's commands and options
4. Execution: All tools follow the same patterns, so knowledge transfers

All Forma tools follow the Forma Protocol:

<tool> <resource> <action> [OPTIONS] [ARGS]

Lists:

{
  "data": [{"id": "1", "name": "Item 1"}, ...],
  "meta": {"count": 10, "timestamp": "2025-01-28T12:00:00Z"}
}

Single items:

{
  "data": {"id": "1", "name": "Item 1", ...},
  "meta": {"timestamp": "2025-01-28T12:00:00Z"}
}

# stdout = data only (JSON when --json)
# stderr = human output (progress, errors, tables)
xero invoices list --json 2>/dev/null | jq '.data[0]'

Forma tools use forma_auth for unified credential storage:

• OS Keyring as primary storage (macOS Keychain, Windows Credential Manager)
• .env file fallback when keyring is unavailable
• Environment variables override for CI/testing

xero auth login          # Store credentials
xero auth status --json  # Check where credentials come from
xero auth logout         # Remove credentials

# Copy the template
copier copy templates/cli-tool ./my-tool

# Install in development mode
cd my-tool && uv pip install -e .

# Register with Forma
forma sync

1. pyproject.toml with [tool.forma] section
2. CLI entry point following the protocol ({data, meta} envelope, exit codes, --json)
3. Auth commands if auth required (auth login/status/logout)
4. AGENTS.md for AI assistant context

See the Forma Protocol for the complete specification (27 sections).

See AGENTS.md for discovery patterns, command structure, JSON output shapes, exit codes, and chaining examples.

MIT