carta-cc

Carta

Maps, connects, and remembers your documentation.

Carta is a Claude Code plugin that keeps your project docs honest — auditing for contradictions, embedding reference material into a searchable knowledge base, and surfacing the right context exactly when you need it.

---

The problem (or: how this got built)

Fast-moving projects accumulate documentation debt quietly. You write a spec. An AI agent writes a dozen more files based on it. The spec changes. Three weeks later, four different documents describe the same API endpoint four different ways, and nobody — human or AI — knows which one is right.

This problem gets worse the more you lean on AI agents to help you work. Agents are only as good as the context they can see, and when your docs/ folder is a fog of contradictions and stale frontmatter, you're giving your agent a map that leads off a cliff.

Carta started as a happy accident. While working through a project with a lot of PDFs, datasheets, and fast-changing markdown — the kind of repo where the hardware changes on Thursday and the docs are still describing Wednesday — we built a small structural scanner to flag stale and broken cross-references. Then we added a semantic pass. Then a vector store. Then a /doc-search skill so Claude could query the embedded knowledge directly.

At some point we looked at what we had and realized: this is a thing. It works. It's small, it runs locally, it requires no new services beyond what an LLM-augmented developer already has running. So we generalized it.

---

What Carta does

Three things, tightly integrated:

1. Audit

A two-pass system that runs on a schedule or on demand:

• Structural scanner (zero LLM calls) — detects stale docs, broken related: links, homeless markdown files, and orphaned content. Runs fast, runs often.
• Semantic audit (Claude) — reads the scanner output and checks changed doc pairs for contradictions: version numbers, API endpoints, config values, whatever matters in your domain. Writes a rolling AUDIT_REPORT.md with stable AUDIT-NNN issue IDs that persist across runs.

2. Embed

Ingests your reference material — PDFs, datasheets, manuals, audio transcripts — into a local Qdrant vector store via Ollama. Generates spec_summary blocks for dense documents so the audit agent can cross-reference them without re-reading 200 pages.

3. Search

Natural language recall over everything that's been embedded. Ask Claude what the docs say about rate limiting, authentication flows, power supply constraints, sample naming conventions — whatever's in your knowledge base — and get cited answers back.

---

Good fits

Carta shines in projects where:

• Docs outnumber the people who maintain them. Research repos, hardware projects, API platforms — anywhere the documentation surface area is large relative to the team.
• AI agents are generating or editing docs. Agents don't track contradictions between files. Carta does.
• Reference material lives outside version control. PDFs, datasheets, vendor manuals, meeting transcripts — Carta pulls them into the same queryable knowledge base as your markdown.
• The project changes fast. Embedded firmware, evolving APIs, active research — anything where a doc written last Tuesday might already be wrong by Friday.

Less useful for: simple single-repo projects with a handful of docs, or projects where the docs are already the source of truth and rarely change.

---

Quickstart

Version history: CHANGELOG.md. Install (pipx, venv, PATH): docs/install.md.

Claude Code plugin (recommended)

Add the Carta marketplace to your ~/.claude/settings.json:

{
  "extraKnownMarketplaces": {
    "carta-cc": {
      "source": {
        "source": "github",
        "repo": "Ian-q/Carta"
      }
    }
  }
}

Then install and enable the carta-cc plugin via /plugins in Claude Code. That's it — hooks and skills are registered automatically. Run /carta-init in any project to bootstrap Carta there.

CLI install (pip / uvx / curl)

For use without the Claude Code plugin, or if you want the carta command available directly:

# One-shot (no install required)
uvx --from carta-cc carta init

# Install as a CLI tool (recommended on macOS)
pipx install carta-cc
carta init

# Install directly (may require --user or a venv on macOS/PEP 668 systems)
python3 -m pip install carta-cc
carta init

# Or via curl
curl -fsSL https://raw.githubusercontent.com/Ian-q/Carta/main/carta/install/install.sh | bash

See docs/install.md for pipx vs venv, PATH, PlatformIO conflicts, and --pip-args syntax.

---

Setup (5 minutes)

Prerequisites: