🧱 Monolith

One ruleset. Every agent. Spec to ship.

Monolith is a dependency-free CLI that unifies three concerns for AI-assisted development:

1. Token efficiency — compile one ruleset into Claude Code, OpenAI Codex, and GitHub Copilot's native config files. ~55–70% fewer output tokens.
2. Spec-Driven Development — a full constitution → specify → clarify → plan → analyze → tasks → implement pipeline with structured specs/<feature>/ artifacts.
3. Runtime compression — wrap any command with monolith run to compress its output before the agent reads it.

Agent	File Monolith manages
Claude Code	CLAUDE.md
OpenAI Codex	AGENTS.md
GitHub Copilot	.github/copilot-instructions.md
Cursor	.cursorrules
Windsurf	.windsurfrules
Gemini CLI	GEMINI.md
Aider	CONVENTIONS.md

---

⚡ Before / After

Without Monolith — 84 tokens

Great question! I'd be happy to help you figure this out. So, the reason your function is returning None is actually because there's no explicit return statement at the end of the branch. What you'll want to do here is make sure you return the computed value. I hope this helps, and let me know if you have any other questions!

With Monolith — 19 tokens (−77%)

It returns None because that branch has no return. Return the computed value.

Same answer. ~⅕ the tokens. (Measured by monolith bench.)

---

📦 Install

Requires Python ≥ 3.9. Dependency-free core.

pipx install monolith-ai      # recommended (isolated)
# or
pip install monolith-ai

From source:

git clone https://github.com/keyurpatel446/Monolith && cd Monolith
pip install -e .              # or: pip install -e ".[bench]" for exact token counts

---

🚀 Quickstart

Claude Code (most common — see full guide)

monolith init && monolith apply --agent claude && monolith doctor

All 7 agents at once

monolith init                 # detect agents, create .monolith/settings.json
monolith apply --agent all    # write all 7 config files in one go
monolith doctor               # verify every agent picked up the rules
monolith stats                # see projected savings + input cost

Spec-Driven Development

monolith constitution                      # scaffold .monolith/memory/constitution.md
monolith specify user-auth                 # scaffold specs/user-auth/spec.md
monolith specify user-auth --plan \
  --data-model --contracts                 # scaffold all artifacts at once
monolith analyze user-auth                 # check spec ↔ plan ↔ tasks consistency
monolith checklist user-auth               # quality gate before shipping

Install the SDD slash commands so any agent can run the workflow:

monolith hub install monolith.constitution
monolith hub install monolith.specify
monolith hub install monolith.clarify
monolith hub install monolith.analyze
monolith hub install monolith.checklist
monolith hub install monolith.implement

---

🤖 Claude Code setup

Full guide: docs/agents/claude-code.md

Claude Code reads CLAUDE.md automatically. Monolith writes its rules there. Three steps and you're done:

1. Install

pipx install monolith-ai

2. Set up your project (run once per repo)

monolith init                  # creates .monolith/settings.json
monolith apply --agent claude  # writes token rules into CLAUDE.md
monolith doctor                # confirms: "[ok ] Claude Code — managed block present"

Open Claude Code in the project — rules are active immediately. No app config needed.

3. Install slash commands (optional but recommended)

# SDD workflow — use /monolith.specify, /monolith.clarify, etc. inside Claude Code
monolith hub install monolith.constitution
monolith hub install monolith.specify
monolith hub install monolith.clarify
monolith hub install monolith.analyze
monolith hub install monolith.checklist
monolith hub install monolith.implement

# Utilities
monolith hub install concise-commit   # /concise-commit  — one-line commit message
monolith hub install terse-review     # /terse-review    — correctness-only review
monolith hub install explain-diff     # /explain-diff    — bullet summary of diff

4. Add the MCP server (optional — compresses command output inside the session)

claude mcp add monolith-shrink -- monolith mcp

5. Compress command output (optional — wrap any command)

monolith run -- pytest -q        # Claude sees failures + summary only (~90% smaller)
monolith run -- ruff check .     # Claude sees diagnostics + counts
monolith run -- git status       # drops hint noise

For Cursor, Windsurf, Copilot, Codex, Gemini CLI, or Aider — see docs/agents/ or just run monolith apply --agent all to write all 7 config files at once.

---

🧰 What you get

Token efficiency

Command	Description
monolith init	Detect agent files and create .monolith/settings.json.
monolith apply [--agent all|claude|codex|copilot|config]	Compile directives into agent configs (idempotent).
monolith tier [name] [--apply]	Show or switch the active compression tier.
monolith stats	Projected + measured reduction and input cost per file.
monolith bench	Run the benchmark corpus and record measured token reduction.
monolith rules list|add|remove [value]	Manage custom directives appended to every block.
monolith doctor	Verify each configured agent has the Monolith block.

Spec-Driven Development (SDD)

Command	Description
monolith constitution	Scaffold .monolith/memory/constitution.md — mission, principles, definition of done.
monolith specify <feature> [--plan] [--data-model] [--contracts]	Scaffold specs/<feature>/ with templated artifact files.
monolith analyze [feature]	Structural cross-artifact check: spec ↔ plan ↔ tasks. Exits 1 on errors.
monolith checklist <feature> [--write]	Generate a quality gate checklist pre-checked against existing artifacts.

Task management

Command	Description
monolith plan <prd-file> [--force]	Parse a PRD/Markdown file into a task tree; writes TASKS.md.
monolith tasks [--emit]	List the task tree; --emit re-writes TASKS.md.
monolith task <id> --status todo|doing|done	Update a task's status (warns on unmet dependencies).
monolith tasks-to-issues --repo owner/repo	Push todo/doing tasks to GitHub Issues (requires GITHUB_TOKEN).

Resource hub & runtime

Command	Description
monolith hub list|search|show|install	Browse and install curated agent resources (SDD commands + utilities).
monolith shrink [file] [--level lite|full|ultra]	Compress verbose output deterministically.
monolith run -- <command>	Run a command, compress its output, save full output on failure.
monolith gain	Show cumulative token savings from run.
monolith mcp	Experimental MCP server exposing shrink over stdio.
monolith scan [--apply]	Scan repo for @monolith: task/rule tags and apply them.

Global flag --root <dir> runs against another project directory.

---

🗺️ SDD pipeline

Monolith ships a full Spec-Driven Development workflow as both CLI commands and installable slash commands (cross-agent via the hub).

constitution → specify → clarify → plan → analyze → tasks → implement

Each feature gets a structured folder:

specs/
└── user-auth/
    ├── spec.md          # requirements + user stories + acceptance criteria
    ├── plan.md          # architecture + stack decisions + edge cases
    ├── tasks.md         # actionable task breakdown with @after: deps
    ├── data-model.md    # entity definitions + relationships
    ├── checklist.md     # quality gate (auto-generated)
    └── contracts/
        └── README.md    # API contract convention + per-endpoint files

Every slash command (e.g. /monolith.specify) installs into .claude/commands/, .codex/prompts/, and .github/prompts/ simultaneously — author once, run anywhere.

monolith hub list              # see all SDD commands + utilities
monolith hub show monolith.specify

---

🎚️ Tiers

Tier	Intensity	Projected output reduction*
lite	filler removal only	~25–35%
full (default)	filler + dense formatting + no over-engineering	~55–65%
ultra	telegraphic, bullet-first, every directive	~60–70%

* Projections derived from upstream benchmarks. Run monolith bench for a figure measured on the sample corpus.

---

🗂️ Task management

Point monolith plan at a PRD or any structured Markdown file. Headings and list items become tasks; nesting becomes parent/child. Wire up dependencies with inline tags — {#slug} names a task and @after:slug depends on it:

# Auth feature
- Design DB schema {#schema}
- Build API @after:schema
  - Add input validation
## Release @after:schema

monolith plan prd.md writes a shared task store under .monolith/tasks/ and a root TASKS.md your agents read as ordinary project context.

For per-feature task tracking, put the PRD in specs/<feature>/spec.md and use monolith analyze <feature> to check coverage.

---

📚 Documentation

• Usage guide · Capabilities
• Per-agent setup: Claude Code · Codex · Copilot
• Roadmap · Changelog · Contributing
• Security · Publishing
• Analysis — benchmarks, competitor & stability analysis
• Demo: run bash scripts/demo.sh (record with asciinema)

---

_{Keywords: reduce Claude Code token usage · Codex AGENTS.md token efficiency · GitHub Copilot instructions to save tokens · Cursor cursorrules token optimization · Windsurf windsurfrules AI rules · Gemini CLI GEMINI.md project instructions · Aider CONVENTIONS.md project rules · compress AI command output test output for LLMs · cross-agent token optimization CLI · spec-driven development AI workflow · one config for Claude Code Codex Copilot Cursor Windsurf Gemini Aider.}

🌱 Development & branching

Branch	Purpose
master	Default / release branch. Merges here trigger CI to tag a release.
develop	Integration branch for completed features.
feature/<name>	Feature work.
fix/<name>	Bug fixes.

CI (.github/workflows/ci.yml) runs the test suite on every push/PR to master and develop. When code is merged to master, it reads the version from pyproject.toml and, if a matching tag does not yet exist, creates the tag vX.Y.Z and a GitHub release. Bump version in pyproject.toml to cut a new release.

python -m unittest discover -s tests -v   # run the tests locally

☕ Support

Monolith is free and MIT-licensed. If it saves you tokens (and money), consider chipping in for a coffee — it genuinely helps keep the project moving. 🙏

👉 paypal.me/keyurpatel446

📄 License

MIT © Keyur Patel