Metadata-Version: 2.4
Name: monolith-ai
Version: 0.1.9
Summary: Cross-agent token-efficiency layer for AI coding assistants (Claude Code, OpenAI Codex, GitHub Copilot).
Project-URL: Homepage, https://github.com/keyurpatel446/monolith
Project-URL: Roadmap, https://github.com/keyurpatel446/monolith/blob/main/ROADMAP.md
Author-email: Keyur Patel <keyurpatel446@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,claude-code,cli,codex,copilot,llm,tokens
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Provides-Extra: bench
Requires-Dist: tiktoken>=0.5; extra == 'bench'
Description-Content-Type: text/markdown

# 🧱 Monolith

> **One ruleset. Every agent. Fewer tokens.**

[![CI](https://github.com/keyurpatel446/Monolith/actions/workflows/ci.yml/badge.svg)](https://github.com/keyurpatel446/Monolith/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](pyproject.toml)
[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](#-development--branching)
[![Buy me a coffee](https://img.shields.io/badge/Buy%20me%20a%20coffee-PayPal-00457C?logo=paypal&logoColor=white)](https://paypal.me/keyurpatel446)

**Reduce token usage across Claude Code, OpenAI Codex, and GitHub Copilot from one
config.** Monolith is a small, dependency-free CLI that writes proven token-saving
rules into the native instructions file each AI coding agent already reads — so
you author the rules **once** and every agent obeys them:

| Agent | File Monolith generates |
|-------|-------------------------|
| Claude Code | `CLAUDE.md` |
| OpenAI Codex | `AGENTS.md` |
| GitHub Copilot | `.github/copilot-instructions.md` |

It also does **task management** (PRD → tracked tasks), ships a **resource hub**
of installable agent commands, and can **`shrink`** verbose tool output at
runtime — all from one tool.

---

## ⚡ 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`.)

---

## 🪄 Why

Each agent reads instructions from a different file, so today you'd copy-paste
the same rules into three places and keep them in sync by hand. Monolith keeps
one canonical source and compiles it. Re-running is safe: managed content lives
between markers and never clobbers your own notes in the same file.

It unifies what used to take several separate tools into one cross-agent CLI:
token-saving rules, dense-output tiers, task management, a resource hub, and
runtime command-output compression.

## 📦 Install

Requires Python ≥ 3.9. Dependency-free core.

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

From source (current default until the first PyPI release is published):

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

## 🚀 Quickstart

```bash
monolith init                 # detect agents, create .monolith/settings.json
monolith apply --agent all    # write CLAUDE.md, AGENTS.md, copilot-instructions.md
monolith doctor               # verify each agent picked up the rules
monolith tier ultra --apply   # crank up compression
monolith bench                # measure real token reduction on the sample corpus
```

## 🧰 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 the directives into agent configs (idempotent). |
| `monolith tier [name] [--apply]` | Show or switch the active compression tier. |
| `monolith stats` | Show projected reduction, last measured reduction, and the input cost of the block. |
| `monolith bench` | Run the built-in 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. |

**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). |

**Resource hub & runtime**

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

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

## 🎚️ 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, not per-project measurements.
Run `monolith bench` for a figure measured on the sample corpus.

See [docs/CAPABILITIES.md](docs/CAPABILITIES.md) for the full capability list.

## 🗂️ 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:

```markdown
# 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.

## 📚 Documentation

- [Usage guide](docs/USAGE.md) · [Capabilities](docs/CAPABILITIES.md)
- Per-agent setup: [Claude Code](docs/agents/claude-code.md) ·
  [Codex](docs/agents/codex.md) · [Copilot](docs/agents/copilot.md)
- [Roadmap](ROADMAP.md) · [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md)
- [Security](SECURITY.md) · [Publishing](docs/PUBLISHING.md)
- [Analysis](docs/analysis/) — benchmarks, competitor & stability analysis
- Demo: run `bash scripts/demo.sh` (record with asciinema)

---

<sub>Keywords: reduce Claude Code token usage · Codex `AGENTS.md` token efficiency ·
GitHub Copilot instructions to save tokens · compress AI command/test output for
LLMs · cross-agent token optimization CLI · one config for Claude Code, Codex and
Copilot.</sub>

## 🌱 Development & branching

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

CI ([`.github/workflows/ci.yml`](.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.

```bash
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. 🙏

[![Buy me a coffee via PayPal](https://img.shields.io/badge/☕%20Buy%20me%20a%20coffee-PayPal-00457C?logo=paypal&logoColor=white&style=for-the-badge)](https://paypal.me/keyurpatel446)

> 👉 **[paypal.me/keyurpatel446](https://paypal.me/keyurpatel446)**

## 📄 License

MIT © Keyur Patel
