Mantle
AI workflow engine with persistent context. Built for developers who use Claude Code.
The Problem
AI coding agents are stateless. Every session starts from zero — context is lost, decisions are forgotten, and you end up repeating yourself or pasting notes between tools. Worse, agents rubber-stamp bad ideas instead of challenging them.
Mantle fixes this by giving your AI agent a memory, a structured workflow, and the discipline to validate ideas before building them.
What It Does
Mantle manages the full lifecycle of AI-assisted development:
Idea to verified code in one command — /mantle:build runs the full pipeline automatically: shape the issue, plan stories, implement with per-story agents, simplify, and verify against acceptance criteria.
Persistent context — project state, decisions, session logs, and a personal knowledge vault stored as markdown with YAML frontmatter. Everything is human-readable and lives in .mantle/.
Auto-briefing — every Claude Code session starts with a compiled briefing: project state, last session log, open blockers, next actions. You never start from zero.
Compiled knowledge — vault state is pre-compiled into Claude Code commands so your AI gets instant context, not expensive runtime file queries.
Cross-project learning — a personal vault links skills, patterns, and lessons learned across projects via Obsidian wikilinks. Learnings from past issues auto-surface in future planning.
Global storage — store .mantle/ context at ~/.mantle/ instead of in-repo for workplace environments where modifying .gitignore isn't desirable. Project identity is derived from git remote URL, so context survives re-clones.
Quick Start
Requires Python 3.14+.
# Install
uv tool install mantle-ai
# Mount commands into Claude Code
mantle install
# Initialize a project
cd your-project
mantle init
# Set up a personal vault (optional)
mantle init-vault ~/vault
Once initialized, .mantle/ is created in your project. Start a Claude Code session and use /mantle:help to see available commands.
Already have an existing project? Run mantle init then /mantle:adopt — AI agents analyze your codebase and domain, then interactively generate product and system design documents from what already exists.
Using this at work? Store context outside the repo so it never shows up in git diffs:
mantle storage --mode global
mantle migrate-storage --direction global
Context moves to ~/.mantle/projects/<repo-identity>/. All commands work identically — the path resolution is transparent.
Workflow
Every phase is a /mantle:* slash command inside Claude Code. Run them individually for control, or use /mantle:build to automate the full pipeline from shaped issue to verified code.
Project Setup (once)
| Phase | Command | What It Does |
|---|---|---|
| Idea | /mantle:idea |
Capture your idea with structured metadata — hypothesis, target user, success criteria. Saved as .mantle/idea.md. |
| Challenge | /mantle:challenge |
Optional. AI stress-tests your idea from multiple angles (devil's advocate, pre-mortem, competitive analysis). Produces a verdict with confidence level. |
| Research | /mantle:research |
Optional. Web research to validate technical feasibility and explore existing solutions. Reports saved to .mantle/research/. |
| Product Design | /mantle:design-product |
Interactive session defining the what and why — features, target users, user stories, release milestones. Creates .mantle/product-design.md. |
| System Design | /mantle:design-system |
Interactive session defining the how — architecture, tech choices, data model. Every decision logged with rationale and alternatives. Creates .mantle/system-design.md. |
Already have an existing project? Run /mantle:adopt instead — AI agents analyze your codebase and domain, then interactively generate product and system design documents from what already exists.
Per-Issue Cycle (repeat for each issue)
| Phase | Command | What It Does |
|---|---|---|
| Plan Issues | /mantle:plan-issues |
Break work into vertical slices. AI proposes one issue at a time — you approve or adjust each before the next. |
| Shape Issue | /mantle:shape-issue |
Evaluate 2-3 approaches with tradeoffs before committing to a direction. Past learnings are loaded automatically. |
| Plan Stories | /mantle:plan-stories |
Decompose the issue into implementable stories sized for a single AI context window. Each story includes test expectations (TDD). |
| Implement | /mantle:implement |
Automated build loop — spawns an Agent per story with dependency-aware wave execution, runs tests, retries once on failure, post-implementation code review, atomic git commits. |
| Simplify | /mantle:simplify |
Post-implementation quality gate. Per-file agents identify and remove AI-generated code bloat. Test-gated — changes only committed if tests pass. |
| Verify | /mantle:verify |
Project-specific verification against acceptance criteria. Auto-detects test/lint/check commands on first use. Per-issue overrides supported. |
| Review | /mantle:review |
Human review with acceptance criteria checklist. AI presents pass/fail status from verification. You approve or request changes per criterion. |
| Retrospective | /mantle:retrospective |
Capture what went well, what was harder than expected, and wrong assumptions. Learnings auto-surface in future shaping sessions. |
Or run it all at once: /mantle:build executes the full pipeline — shape, plan stories, implement, simplify, and verify — without requiring confirmation at each step.
Available Any Time
| Command | What It Does |
|---|---|
/mantle:bug |
Quick structured bug capture. Open bugs surface during planning. |
/mantle:inbox |
Ultra-low-friction idea capture for feature ideas. |
/mantle:add-issue |
Add a single new issue to the backlog. |
/mantle:brainstorm |
Explore and validate a feature idea against your product vision. |
/mantle:scout |
Analyze an external repo through your project's design lens. |
/mantle:refactor |
Structured refactoring for architectural debt and design problems. |
/mantle:fix |
Read saved review feedback and fix flagged criteria. |
/mantle:revise-product |
Update the product design. Creates a decision log entry. |
/mantle:revise-system |
Update the system design. Creates a decision log entry. |
/mantle:status |
Show current project state compiled from vault data. |
/mantle:resume |
Re-display the project briefing mid-session. |
/mantle:add-skill |
Add a skill node to your personal vault for cross-project knowledge. |
/mantle:query |
Search your vault knowledge and synthesize a grounded answer. |
/mantle:distill |
Synthesize accumulated vault knowledge on a topic into a persistent note. |
/mantle:help |
List all commands grouped by phase. |
Knowledge Engine
Every AI context window is expensive. Mantle makes each one smarter by injecting the right knowledge at the right time — domain expertise, past learnings, and project decisions that would otherwise be lost between sessions.
How it works
Your personal vault (~/vault/) is a knowledge graph of interconnected skill nodes, each containing domain-specific patterns, conventions, anti-patterns, and lessons learned. When you start working on an issue, Mantle auto-detects which skills are relevant, compiles them into .claude/skills/, and Claude Code natively loads them. Every agent — whether it's shaping an approach, implementing a story, or reviewing code — gets pre-loaded domain knowledge without burning context on file searches.
The compounding effect: learnings from Issue 5 improve how Issue 12 is shaped. A skill you built while working on Project A informs implementation on Project B. The knowledge graph grows with you, not per-project.
Knowledge commands
| Command | What It Does |
|---|---|
/mantle:add-skill |
Create a skill node in your personal vault — proficiency level, patterns, anti-patterns, related skills. Builds the graph. |
/mantle:query |
Search your accumulated vault knowledge and synthesize a grounded answer. Like asking your past self for advice. |
/mantle:distill |
Synthesize scattered vault knowledge on a topic into a single, dense reference note. Turns experience into reusable context. |
/mantle:retrospective |
After completing an issue, capture what went well and what was harder than expected. These learnings auto-surface in future /mantle:shape-issue sessions. |
/mantle:scout |
Analyze an external repo through your project's design lens. Extract patterns and ideas grounded in your existing architecture. |
What gets injected into each context window
- Session briefing — project state, last session log, blockers, next actions (auto-loaded on session start)
- Compiled skills — domain-specific patterns matched to the current issue's technologies
- Past learnings — gotchas, recommendations, and wrong assumptions from previous issues
- Decision log — architectural choices with rationale, so agents honour past decisions instead of re-debating them
The result: agents that know your project's conventions, remember past mistakes, and make informed tradeoff decisions — every session, automatically.
Lifecycle hooks
Mantle invokes user-supplied shell scripts on issue lifecycle events so you can push status updates to Linear, Jira, Slack, or any other tracker — without mantle ever importing a tracker library or holding credentials.
Convention
Drop an executable script at <mantle-dir>/hooks/on-<event>.sh:
| Event | Fires after |
|---|---|
issue-shaped |
/mantle:shape-issue saves a shaped issue |
issue-implement-start |
issue transitions to implementing |
issue-verify-done |
issue transitions to verified |
issue-review-approved |
issue transitions to approved |
Your script is invoked with:
$1— issue number$2— new status$3— issue title
Missing scripts are a silent no-op. Non-zero exits log a warning and the workflow continues (hook failures never block mantle).
Config passthrough
Any dict under hooks_env: in <mantle-dir>/config.md frontmatter is
exported as environment variables to the hook process. Keys are opaque —
mantle never interprets them.
---
hooks_env:
LINEAR_API_KEY: lin_api_xxx
JIRA_PROJECT_KEY: PLAT
---
Quick start with shipped examples
mantle show-hook-example linear > .mantle/hooks/on-issue-shaped.sh
chmod +x .mantle/hooks/on-issue-shaped.sh
Available examples: linear, jira, slack. Each contains a setup
header documenting the CLI/API install, auth steps, and required env vars.
How It Works
Mantle is a Python CLI (mantle) that also installs slash commands into Claude Code (/mantle:*). The core library handles all state and vault operations. The CLI is a thin wrapper. Claude Code commands compile context from your vault and orchestrate AI-assisted workflows.
Architecture: core/ (all business logic) → cli/ (thin routing layer) → Claude Code commands (prompt-based orchestration). Core never imports from CLI. Each implementation story gets a fresh 200k context window via native Agent subagents.
Storage: All state lives in plain markdown files with YAML frontmatter — human-readable and editable by hand. By default, .mantle/ lives in your project root (git-tracked for collaboration). For workplace environments, switch to global storage at ~/.mantle/ with mantle storage --mode global.
Session continuity: A SessionStart hook auto-compiles context and displays a project briefing. Session logs are written automatically at the end of every session, so you never lose context between conversations.
Status
v0.23.0 — Regression-safety net for upcoming token-cost work. Three landed pieces: (a) a prompt-layer golden-parity test harness (#90) with normalized snapshots for /mantle:build, /mantle:implement, and /mantle:plan-stories plus a coverage-policy test that fails CI if a new /mantle:* command lands without a parity classification; (b) per-stage build telemetry (#92) — a universal mantle stage-begin primitive plus a sub-agent JSONL read path under <parent_session>/subagents/, so every build report attributes tokens, wall-clock, and dollar cost per stage rather than collapsing the whole build into one bucket; (c) a post-hoc A/B harness (#89) — mantle ab-build-compare <baseline.md> <candidate.md> renders a stage-grouped delta report (tokens, seconds, cost) from any two recorded build reports, with prices resolved from .mantle/cost-policy.md. Together these unlock confident token-cut refactors in v0.24.0 by making prompt drift, per-stage cost, and cross-build comparisons all observable.
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for mantle-ai 0.23.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| mantle_ai-0.23.0.tar.gz | 1.4 MB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| mantle_ai-0.23.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.7 MB
Release files / mantle_ai-0.23.0.tar.gz
| Download URL | mantle_ai-0.23.0.tar.gz |
|---|---|
| Size | 1.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
628d402888d5382f02e34476f0308eeff25c23e5f7eb8a091f146a1df2ae8859
|
|
BLAKE2b-256 checksum How to use checksums |
55c05adc07f54241189d8d128b46793cf14d374d293fa897cec1fd455509a7f0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / mantle_ai-0.23.0-py3-none-any.whl
| Download URL | mantle_ai-0.23.0-py3-none-any.whl |
|---|---|
| Size | 281.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c30506034c48047214c84b5ae8fd8bf92ae859e5ce091b98e95fc15f71303aff
|
|
BLAKE2b-256 checksum How to use checksums |
e771bb8b84b9ae699f76b19f07499d5ee6b7ff839086e46b5721fc5db28e1a94
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for mantle-ai 0.23.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
