Attune AI
Persistent memory and receipt-verified workflows for Claude Code.
🌐 Docs & guides: attune-ai.dev
Your agent stops starting from zero, its word stops being the evidence, and it asks you with structure instead of prose.
Memory: a stash → recall → promote loop carries decisions, bugs,
and hard-won lessons from one session into the next, and surfaces the
right lesson at the exact moment a prompt needs it. Local-first, from
a plain pip install attune-ai. Recall loads a few hundred
exactly-relevant tokens instead of your whole corpus — 67× fewer
tokens on our own 800+ lesson store, retrieved at P@3 96% on a
frozen benchmark (details).
Receipts: state the outcome you want and how to verify it, and get back a receipt — not a promise:
attune fix "imports resolve after the rename" \
--scope src/attune/cli_minimal.py \
--probe "pytest tests/unit/test_cli_minimal.py" \
--run
The probes are re-run independently of the workflow that claims it finished. Exit 0 means the probes passed — not that the agent felt good about it.
Interactive forms: the agent asks with structure, not prose — a decision card with its recommendation and tradeoffs, a pushback card when it disagrees, a progress report, a ranking or triage — one tap each, validated on the way back. One form renders to whatever surface your client draws: a native dialog, a rich widget, or a plain menu (the vocabulary).
Around that core: 21 workflows and 61 MCP tools dispatching 2–6 domain-specific subagents behind Socratic quality gates, RAG grounding with a citation-per-claim contract, and generation fact-checking — one install, one MCP server. We run our own knowledge base on it: the docs and 800+ engineering lessons at attune-ai.dev are authored, grounded, and maintained by Attune's own stack.
Contents: Install · Costs · Memory · Receipts · Multi-LLM · Workflows & tools · Forms · Accuracy · Install options · Privacy
Get Started in 60 Seconds
Plugin (works standalone)
claude plugin marketplace add Smart-AI-Memory/attune-ai
claude plugin install attune-ai@attune-ai
Then say "what can attune do?" in Claude Code.
Add the Python package (unlocks CLI + MCP)
pip install attune-ai
attune # shows your next steps
Then check your setup with attune validate and run your first
workflow: attune workflow run code-review --path src/.
Setup fight you? Tell me where — I'm actively fixing this.
What each layer adds
| Capability | Plugin only | Plugin + pip |
|---|---|---|
| 28 auto-triggering skills | Yes | Yes |
| Security hooks | Yes | Yes |
| Prompt-based analysis | Yes | Yes |
| 61 MCP tools | -- | Yes |
attune CLI + multi-agent workflows |
-- | Yes |
Ops dashboard (attune ops) — run history, cost tiles, telemetry |
-- | Yes |
What this costs
| How you run it | What it costs |
|---|---|
| Plugin in Claude Code (skills, hooks, forms) | Your Claude subscription. No API key, no extra charge. |
attune CLI + MCP tools |
Direct Anthropic API calls — needs ANTHROPIC_API_KEY with API credits. |
The one thing people get wrong: a Claude Pro/Max subscription does not include API credits — they are separate products. If you only use the plugin, this never comes up. Free on either path (they never call a model): elicitation forms, security hooks, path validation, memory storage and recall, and every local transform.
New in 13.0.0 — correctness you can trust under failure
The code paths that only matter when something goes wrong got a
library-wide review. Memory writes that reported success without
landing now actually persist or surface the failure; telemetry and
security-gate state a single malformed record could corrupt are
locked down; external input that could crash a parse now degrades
instead. Shared stores (AgentStateStore, ComplianceDatabase) write
atomically under a lock. And agents gain interactive forms — richer
than yes/no: a decision card with per-option tradeoffs, a pushback card
for disagreement, progress reports, plus ranking, triage, and more, each
rendered to whatever surface your client supports — a native dialog, an
HTML widget, or multiple-choice (via attune-forms 0.7.0). The major
bump is the removal of
the dormant in-package hook-execution engine — dead code with no live
caller (the hooks Claude Code runs are unchanged); the
memory-durability and schema changes alter observable behavior, so
check the CHANGELOG's migration notes if you depend on them.
The memory suite — measured
Stash on stop. Recall at the door. Promote what endures.
- Stash — a
Stophook extracts decisions, bugs, and references from the session and writes them to the memory store (local file by default, Redis Agent Memory Server when reachable). - Recall — a
SessionStarthook surfaces the most recent findings for your project;/recall <topic>searches on demand. - Promote — a reviewed stash→curated path lands git-tracked
.mdfiles in your corpus. Files are the store; Redis serves them. - Lessons at the trap moment — hooks retrieve the exact lesson a prompt or tool call needs, budget-capped no matter how large the corpus grows.
Memory is local-first — nothing leaves your machine, and without Redis everything degrades to the file backend with clear guidance. The economics are measured, not promised (2026-07-05 snapshot; ratios improve as the corpus grows):
| Memory-suite recall | Instead of loading | You load | Win |
|---|---|---|---|
| Trap-moment lessons | 202,042 tok (583 lessons) | ≤3,000 tok | 67× fewer tokens |
| SessionStart digest | 16 corpus files (4.6 ms) | one Redis call (0.6 ms) | ~7× faster |
Numbers from benchmarks/memory_savings.py on our dogfood store.
Receipts, not promises
If you know acceptance-test-driven development, this is that rebuilt for agent workflows: acceptance probes are declared up front, and the agent's own word is never the evidence.
- Fix Receipts (
attune fix) — outcome-first fixing. Preview a contract (done conditions, constraints, probes) with nothing executing; add--runfor an attributed diff whose probes are re-run independently. Exit 0 only when the probes pass. - Spec Ladders (
/spec) — goal-driven specs you approve rung by rung: requirements, design, and a gated task ladder, every ruling recorded in a decision file that outlives the session. - Guided intakes —
/fixand/speccompose their contracts through a form: goal pre-filled, scope picker from paths you've touched, probe suggestions from matching tests. - Receipts all the way down — a failed or absent security auditor fails the Security gate; spec-closure claims draw a rotating skeptic seat; risk-class diffs authored by the lead model are reviewed by a different model before promotion.
Multi-LLM collaboration
As of 10.6.0, attune treats Claude Code, OpenAI Codex, and Google Antigravity as seats at the same table — with the discipline that a claim without a receipt doesn't ship:
/roundtable— the three models deliberate a question on a Redis-backed board; you chair what gets promoted./cross-review— an advisory second opinion on a real diff from a different model than the one that wrote it.- Cross-provider handoff + shared session memory — portable resume briefs and a provider-neutral stash/recall surface with a PII/secrets gate that redacts at rest and fails closed.
- A projected collaboration contract — one master file projects
to
AGENTS.mdand per-provider mirrors.
Codex installs the same plugin from its marketplace
(codex plugin install attune-ai@attune-ai); Antigravity connects
over MCP. The 10.6.1 release exists because a cross-provider receipt
probe caught a protocol bug the primary client silently tolerated.
Workflows and MCP tools
Skills trigger from natural language — "review my code", "scan for
vulns", "generate tests", "plan this feature" — and every workflow
dispatches 2–6 subagents (Opus for deep reasoning, Sonnet for
analysis, Haiku for fast scanning), synthesized by an orchestrator.
Ready-made Claude Code subagents (security-reviewer, spec-author,
refactor-planner, …) appear in your /agents list on install.
All 21 workflows
| Workflow | Agents | What It Does |
|---|---|---|
| code-review | security, quality, perf, architect | 4-perspective code review |
| security-audit | vuln-scanner, secret-detector, auth-reviewer, remediation | Finds vulnerabilities and generates fix plans |
| deep-review | security, quality, test-gap | Multi-pass deep analysis |
| perf-audit | complexity, bottleneck, optimization | Identifies bottlenecks and O(n²) patterns |
| bug-predict | pattern-scanner, risk-correlator, prevention | Predicts likely failure points |
| health-check | dynamic team (2–6) | Project health across tests, deps, lint, CI, docs, security |
| test-gen | identifier, designer, writer | Writes pytest code for untested functions |
| test-audit | coverage, gap-analyzer, planner | Audits coverage and prioritizes gaps |
| doc-gen | outline, content, polish | Generates documentation from source |
| doc-audit | staleness, accuracy, gap-finder | Finds stale docs and drift |
| dependency-check | inventory, update-advisor | Audits outdated packages and advisories |
| refactor-plan | debt-scanner, impact, plan-generator | Plans large-scale refactors |
| simplify-code | complexity, simplification, safety | Proposes simplifications with safety review |
| release-prep | health, security, changelog, assessor | Go/no-go readiness check |
| release-gate | parallel agent team (4 stages) | Release readiness assessment / go-no-go gate |
| release-notes | agent-prep | Drafts release notes + LLM readiness advice |
| doc-orchestrator | inventory, outline, content, polish | Full-project documentation |
| secure-release | security, health, dep-auditor, gater | Release pipeline with risk scoring |
| research-synthesis | summarizer, pattern-analyst, writer | Multi-source research synthesis |
| discovery-sweep | pattern-scanner, verifier | Repo-wide bug-pattern sweep with verification |
| rag-code-gen | retriever, generator | Citation-forced code generation grounded in the local corpus |
| orchestrated-health-check | dynamic team | health-check with explicit meta-orchestration |
| fix | agent-fix | Minimal in-place fix within a contract's scope, verified by a receipt |
All 61 MCP tools — 50 core in 7 categories, plus 11 memory tools registered by the bundled Redis plugin
Workflow (22): security_audit code_review bug_predict
discovery_sweep performance_audit refactor_plan simplify_code
deep_review test_generation test_audit test_gen_parallel
doc_gen doc_audit doc_orchestrator release_notes
health_check dependency_check secure_release
research_synthesis analyze_batch analyze_image
rag_knowledge_query
Help (5): help_lookup help_init help_status help_update
help_maintain
Memory (4): memory_store memory_retrieve memory_search
memory_forget
Personal Memory (4): personal_memory_capture
personal_memory_recall personal_memory_topics
personal_memory_forget
Utility (8): auth_status auth_recommend telemetry_stats
context_get context_set attune_get_level attune_set_level
list_capabilities
Elicitation (5): elicitation_ask elicitation_render_form
elicitation_collect_response elicitation_render_widget
chart_render_widget
Handoff (2): handoff_create handoff_resume
Redis memory (11): session_memory_*, redis_memory_*,
redis_health_check
Interactive forms — the agent asks with structure
Agent↔you exchanges are interactive forms, not prose Q&A. The agent presents a decision with its recommendation, rationale, and per-option tradeoffs; disagrees through a pushback card (your approach vs. its alternative, side by side); reports progress as done / in-flight / blocked; and has you rank, triage, confirm, deliberate, or review its assumptions — one tap each. Every question is validated on the way back, so a malformed answer is re-asked, not silently accepted.
One declarative form, written once, renders to the richest surface your
client supports — a native dialog, a rich HTML widget, or a plain
multiple-choice menu on a text-only surface — so the same question
works everywhere and degrades gracefully. The full construct vocabulary
ships via attune-forms 0.7.0 (new in 13.0.0). Chart specs render
through the same sealed SVG kernel (chart_render_widget, nine chart
types).
Accuracy & Faithfulness
RAG generation enforces citation-per-claim: 0.98 mean per-claim faithfulness, CI-gated at ≥ 0.97 (40-query golden set, N=20 runs). The contract was chosen by A/B measurement — the per-query hallucination bucket rate dropped from 46.7% to 6.7% with it (methodology). Retrieved passages are sentinel-wrapped against prompt injection. The help resolver passes 48/48 benchmark queries at P@1 (golden set).
Installation Options
pip install attune-ai works out of the box — the CLI, all
workflows, the MCP server, RAG (attune-rag and attune-verify are
core dependencies), cross-session memory, and the Agent SDK. Memory
features activate when a Redis Stack server is reachable and degrade
with guidance when not. Add extras only for the surfaces you use:
| You want | Install |
|---|---|
| Everything most users need, incl. Redis memory | pip install attune-ai |
| Claude API mode + optional LangChain/LangGraph interop adapters | pip install 'attune-ai[developer]' |
The ops dashboard (attune ops) |
pip install 'attune-ai[ops]' |
Extras combine — pip install 'attune-ai[developer,ops]'. Keep the
quotes: zsh and bash treat square brackets as glob characters.
Contributing? Clone and install the dev toolchain instead:
git clone https://github.com/Smart-AI-Memory/attune-ai.git
cd attune-ai && pip install -e '.[dev]'
API mode
The CLI and MCP tools call the Anthropic API directly (the plugin never needs this):
export ANTHROPIC_API_KEY="sk-ant-..." # requires API credits
export REDIS_URL="redis://localhost:6379" # optional
Model routing assigns Opus/Sonnet/Haiku by task complexity
(ATTUNE_AGENT_MODEL_* to override); depth budgets run $0.50 /
$2.00 / $5.00 (ATTUNE_MAX_BUDGET_USD to override); --cheap
forces pattern-matching workflows onto Haiku. Live spend tiles on
the dashboard (attune ops).
Platform support
| Platform | Support |
|---|---|
| macOS / Linux / WSL2 | Full |
| Windows native + Git Bash | Supported (Bash tool, POSIX-ish syntax) |
| Windows native + PowerShell tool | Limited — security validation fails closed |
Redis has no native Windows build — use Docker
(docker run -d -p 6379:6379 redis:7-alpine). Without reachable
Redis, memory degrades gracefully to the file backend and
attune.memory.session_stash.backend_status() reports
fallback: true.
Ecosystem
| Package | Role | Install |
|---|---|---|
attune-ai |
Developer workflow hub (this package) | pip install attune-ai |
attune-rag |
RAG pipeline (core dep) | bundled |
attune-verify |
Generation fact-checker (core dep) | bundled |
attune.authoring |
Help authoring + staleness detection (absorbed the former attune-author package in 11.0.0) |
bundled |
attune-help |
Progressive-depth template runtime | pip install attune-help |
Security, Privacy & Telemetry
Path traversal protection on all file ops, a PreToolUse guard that blocks eval/exec, MCP rate limiting, prompt sanitization, and automated scanning (CodeQL, bandit, detect-secrets) — details in SECURITY.md.
Usage data is local-first. An opt-in, anonymous usage ping
(OFF by default) carries only package, version, workflow name, OS,
Python version, a resettable anonymous id, and a timestamp — never
paths, code, prompts, or filenames; the payload is frozen in source
and guarded by a regression test. attune telemetry status|enable|disable;
DO_NOT_TRACK=1 always wins.
Links
Apache License 2.0 — Free and open source.
If you find Attune useful, give it a star — it helps others discover the project.
Acknowledgments
- Anthropic — For Claude AI, the Model Context Protocol, and the Agent SDK patterns behind the multi-agent orchestration layer
- Boris Cherny — Creator of Claude Code, whose workflow posts validated Attune's plan-first, multi-agent approach
- Affaan Mustafa — For battle-tested Claude Code configurations that inspired the hook system
Built by Patrick Roebuck using Claude Code.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file attune_ai-13.0.0.tar.gz.
File metadata
- Download URL: attune_ai-13.0.0.tar.gz
- Upload date:
- Size: 2.3 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
4a3b5e2802b8c3e04edc151449eba8bffb315404a8d4ab6d86a96d114ecaea19
|
|
| MD5 |
c12d84d3d831983689ffd515b7b36eb9
|
|
| BLAKE2b-256 |
74335b88338a1497f9f9edcb41411e93f8e563cb4be51fa247d67e2223ab33be
|
Provenance
The following attestation bundles were made for attune_ai-13.0.0.tar.gz:
Publisher:
publish-pypi.yml on Smart-AI-Memory/attune-ai
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
attune_ai-13.0.0.tar.gz -
Subject digest:
4a3b5e2802b8c3e04edc151449eba8bffb315404a8d4ab6d86a96d114ecaea19 - Sigstore transparency entry: 2539052586
- Sigstore integration time:
-
Permalink:
Smart-AI-Memory/attune-ai@d9cfa9c46026c135cc61660d356eb0ae66616e7c -
Branch / Tag:
refs/tags/v13.0.0 - Owner: https://github.com/Smart-AI-Memory
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish-pypi.yml@d9cfa9c46026c135cc61660d356eb0ae66616e7c -
Trigger Event:
push
-
Statement type:
File details
Details for the file attune_ai-13.0.0-py3-none-any.whl.
File metadata
- Download URL: attune_ai-13.0.0-py3-none-any.whl
- Upload date:
- Size: 2.4 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
94cfac97c2f6ff7d9e68e90b6728154017a87845ae511795623936000fdc7dfc
|
|
| MD5 |
14aea3bbb4d19ef790e89541419aa1b4
|
|
| BLAKE2b-256 |
91b8364486c0809e32c89112d215e2649b1934ae17ed2445f92434614f921399
|
Provenance
The following attestation bundles were made for attune_ai-13.0.0-py3-none-any.whl:
Publisher:
publish-pypi.yml on Smart-AI-Memory/attune-ai
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
attune_ai-13.0.0-py3-none-any.whl -
Subject digest:
94cfac97c2f6ff7d9e68e90b6728154017a87845ae511795623936000fdc7dfc - Sigstore transparency entry: 2539052772
- Sigstore integration time:
-
Permalink:
Smart-AI-Memory/attune-ai@d9cfa9c46026c135cc61660d356eb0ae66616e7c -
Branch / Tag:
refs/tags/v13.0.0 - Owner: https://github.com/Smart-AI-Memory
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish-pypi.yml@d9cfa9c46026c135cc61660d356eb0ae66616e7c -
Trigger Event:
push
-
Statement type:
