Metadata-Version: 2.4
Name: keephive
Version: 1.0.0
Summary: A knowledge sidecar for Claude Code
Keywords: claude,memory,verification,claude-code,mcp,agent
Author: Jory
Author-email: Jory <jory@pestorious.com>
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Environment :: Console
Requires-Dist: pydantic>=2.12.5
Requires-Dist: rich>=14.3.2
Requires-Dist: mcp>=1.8.0
Requires-Dist: anthropic>=0.40
Requires-Python: >=3.13
Project-URL: Changelog, https://github.com/joryeugene/keephive/blob/main/CHANGELOG.md
Project-URL: Homepage, https://github.com/joryeugene/keephive
Project-URL: Issues, https://github.com/joryeugene/keephive/issues
Project-URL: Repository, https://github.com/joryeugene/keephive
Description-Content-Type: text/markdown

# keephive

<p align="center">
  <a href="https://github.com/joryeugene/keephive/actions/workflows/ci.yml"><img src="https://github.com/joryeugene/keephive/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://pypi.org/project/keephive/"><img src="https://img.shields.io/pypi/v/keephive.svg" alt="PyPI"></a>
  <a href="https://pypi.org/project/keephive/"><img src="https://img.shields.io/pypi/pyversions/keephive.svg" alt="Python"></a>
  <a href="https://github.com/joryeugene/keephive/releases/latest"><img src="https://img.shields.io/github/v/release/joryeugene/keephive.svg" alt="GitHub release"></a>
  <a href="https://github.com/joryeugene/keephive/blob/main/LICENSE"><img src="https://img.shields.io/github/license/joryeugene/keephive.svg" alt="License"></a>
</p>

<table><tr>
<td>
  <h3>A knowledge sidecar for AI agents</h3>
  <p>Claude Code gets the full hook stack; every MCP-aware agent can tap the same memory, log, and audit tools.</p>
</td>
<td align="center">
  <img src="https://raw.githubusercontent.com/joryeugene/keephive/main/assets/mascot.png" width="240" alt="keephive mascot" />
</td>
</tr></table>

## TLDR

1. **Install**: `curl -fsSL https://raw.githubusercontent.com/joryeugene/keephive/main/install.sh | bash`
2. **Connect your agent.** Claude Code discovers seven hooks automatically. Any MCP client can run `keephive mcp-serve` and call the same tools.
3. **Look around**: `hive status` (`h s`), `hive log` (`h l`), `hive todo`
4. **Visual overview**: `hive serve` (`h ws`) opens a browser dashboard at localhost:3847
5. **Periodic cleanup**: `hive verify` (`h v`), `hive reflect` (`h rf`), `hive audit` (`h a`)

> [!NOTE]
> Not on Claude Code? Run `keephive mcp-serve`, point your MCP-compatible agent at the stdio endpoint, and you still get memory, recall, audit, and dashboard tooling.

Everything else on this page is optional depth.

> [!TIP]
> **Shortcuts everywhere.** Three CLI names: `keephive`, `hive`, `h`. Every command
> has a short alias (`h s`, `h r`, `h rc`, `h v`, `h rf`, `h a`). Guides and
> prompts resolve by slug, prefix, or substring:
> ```
> h p pr-re        →  pr-review-git-staged-diff-analysis.md
> h k agent        →  agent-principles.md
> h n code-review  →  starts note from code-review prompt template
> h go pr-re       →  launches session with pr-review prompt loaded
> ```
> You never type a full name. Two keystrokes for the command, a few more for the target.

<p align="center">
  <img src="https://raw.githubusercontent.com/joryeugene/keephive/main/assets/dashboard-home.png" width="800" alt="keephive dashboard" />
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/joryeugene/keephive/main/assets/keepbee.gif" width="100" alt="keepbee" />
</p>

After a few sessions, `hive` shows what your agent has learned:

<p align="center">
  <img src="https://raw.githubusercontent.com/joryeugene/keephive/main/assets/cli-demo.gif" width="700" alt="keephive CLI demo" />
</p>

Keep your agent orientated across platforms. The new <code>hive serve /brain</code> view condenses working memory, rules, TODOs, and platform telemetry into a single high-density dashboard. It highlights the active backend, queued LLM work, and which agents (Claude, Gemini, Codex) are feeding data back into keephive.

<details>
<summary>Text output</summary>

```console
$ hive
keephive v1.0.0
  ● hooks  ● mcp  ● data

  4 facts (4 ok) | 12 today | 8 yesterday | 2 guides | 48K
  42 cmds today · 120 this week · 5d streak ▁▂▅▃█▇▂▁▁▃▅▆▇█▂▁▁▁▁▁▁▁▁

  1 open TODO(s):
    [today] Add rate limiting to the /upload endpoint.

  Today:
  ~ [10:42:15] FACT: Auth service uses JWT with RS256, tokens expire after 1h.
  ~ [10:38:01] DECISION: Chose Postgres over SQLite for multi-user support.
  ~ [09:15:44] INSIGHT: The retry logic in api_client.py silently swallows 429s.
  [09:12:30] DONE: Migrate user table to new schema.

  Active draft: slot 1 · "api testing todo list..." (47 words)  ->  hive nc

  hive go (session) | hive l (log) | hive rf (reflect) | hive help
```

</details>

---

## Install

```bash
curl -fsSL https://raw.githubusercontent.com/joryeugene/keephive/main/install.sh | bash
```

One command. Installs keephive, registers 7 hooks and an MCP server, and verifies everything. Requires [uv](https://docs.astral.sh/uv/). Run once; re-run after upgrades.

Or install manually:

```bash
uv tool install keephive
keephive setup
```

Via pip:

```bash
pip install keephive
keephive setup
```

From source:

```bash
git clone https://github.com/joryeugene/keephive.git
cd keephive && uv tool install . && keephive setup
```

### Multi-agent setup

- `keephive setup` detects Claude, Gemini, and Codex CLIs and installs the shared `keephive-helper` skill in each environment.
- Gemini and Codex receive lightweight hook shims that mirror the Claude lifecycle so telemetry and captures stay in sync.
- All data now lives under `~/.keephive/`; legacy `~/.claude/hive` installs are migrated with a compatibility symlink.

### Stay up to date

```bash
hive up                    # upgrade in place (recommended)
uv tool upgrade keephive   # manual alternative; run keephive setup after
```

> [!TIP]
> Run `keephive setup` again after upgrading manually to sync hooks and the MCP server registration to the new binary path.

---

## When to use what

### Every day (bread and butter)

| I want to...                       | Command                                    |
| ---------------------------------- | ------------------------------------------ |
| See what's going on                | `hive status` *(hive s)*                   |
| Save something I learned           | `hive remember "FACT: ..."` *(hive r)*     |
| Find something from before         | `hive recall <query>` *(hive rc)*          |
| Track a task                       | `hive todo "fix auth"` *(hive t)*          |
| Mark a task done                   | `hive todo done "auth"` *(hive td)*        |
| See today's log                    | `hive log` *(hive l)*                      |

### Visual overview

| I want to...                       | Command                                    |
| ---------------------------------- | ------------------------------------------ |
| Browse everything in a browser     | `hive serve`                               |
| Quick terminal glance              | `hive status` *(hive s)*                   |
| Watch for changes live             | `hive status --watch`                      |
| See active sessions                | `hive ps`                                  |

### Weekly maintenance (when things accumulate)

| I want to...                       | Command                                    |
| ---------------------------------- | ------------------------------------------ |
| Check if old facts are still true  | `hive verify` *(hive v)*                   |
| Find patterns in daily logs        | `hive reflect` *(hive rf)*                 |
| Get a quality assessment           | `hive audit` *(hive a)*                    |
| Archive old logs                   | `hive gc`                                  |

### Power features (when you need them)

| I want to...                       | Command                                    |
| ---------------------------------- | ------------------------------------------ |
| Launch a focused session           | `hive session` *(hive go)*                 |
| Run a session with a custom prompt | `hive go <prompt>` *(prefix match)*        |
| Edit memory/rules/todos directly   | `hive edit <target>` *(hive e)*            |
| Use a multi-slot scratchpad        | `hive note` *(hive n)*                     |
| Create a knowledge guide           | `hive knowledge edit <name>` *(hive ke)*   |
| Generate a standup                 | `hive standup` *(hive su)*                 |

---

## How it works

keephive ships two integration layers:

1. **Agent-agnostic CLI + MCP server.** Every `hive` command is available over stdio via `keephive mcp-serve`, so any MCP-compatible agent can capture, recall, verify, and audit without touching the Claude stack.
2. **Agent hook suite (Claude, Gemini, Codex).** When a supported CLI is present, keephive installs the `keephive-helper` skill and hook shims so each agent follows the same capture→recall→verify loop. Claude keeps the rich lifecycle (SessionStart, PreCompact, etc.); Gemini receives SessionStart / BeforeTool / AfterModel Python shims; Codex gets a notify bridge. All hooks call the same `hive` commands and write normalized telemetry under `~/.keephive/telemetry/<platform>/`.
   - **Hooks** fire on agent events (session start, tool runs, prompt submits) to capture insights and inject context automatically.
   - **MCP server** exposes shared tools (`hive_remember`, `hive_recall`, etc.) so any MCP host can read and write memory directly.
   - **Context injection** still surfaces verified facts, behavioral rules, stale warnings, matching guides, and TODOs at session start via each platform's hook output.

### The loop

```
  capture --> recall --> verify --> correct
     ^                                 |
     +---------------------------------+
```

- **Capture**: The PreCompact hook extracts FACT/DECISION/TODO/INSIGHT entries when conversations compact. It reads the full transcript, classifies insights via LLM, and writes them to today's daily log.
- **Recall**: Captured entries surface automatically at the next session start via context injection. `hive rc` searches all tiers directly; `hive` shows current state.
- **Verify**: Facts carry `[verified:YYYY-MM-DD]` timestamps. After 30 days (configurable), they are flagged stale. `hive v` checks them against the codebase with LLM analysis and tool access.
- **Correct**: Invalid facts get replaced with corrected versions. Valid facts get re-stamped. Uncertain facts get flagged for human review.

### Architecture

The diagram below shows the Claude Code integration path; MCP-only clients reuse the same knowledge store and tools without the hook cycle.

```mermaid
flowchart TD
    subgraph CYCLE["Session Cycle (7 hooks)"]
        direction LR
        START([New session]) -->|"SessionStart:<br>inject context"| WORK([Working])
        WORK -->|"PostToolUse · UserPromptSubmit:<br>nudge, ui-queue inject"| WORK
        WORK -->|"Stop:<br>turn count, micro-nudge"| WORK
        WORK -->|"TaskCompleted:<br>auto-log DONE"| WORK
        WORK -->|context full| PC["PreCompact:<br>extract → log<br>+ pending-facts queue"]
        PC -->|next session| START
        WORK -->|session ends| SEND["SessionEnd:<br>finalize stats"]
    end

    subgraph LLM["LLM Routing (priority chain)"]
        direction LR
        ACLI["claude -p CLI<br>(priority 10, default)"]
        AAPI["Anthropic API<br>(priority 20)"]
        GAPI["Gemini API<br>(priority 25)"]
        OAPI["OpenAI API<br>(priority 30)"]
        NONE["none / offline<br>(priority 99)"]
        ACLI -->|"timeout → non-retriable"| NONE
        ACLI -->|"error in auto mode"| AAPI
        AAPI -->|"error"| GAPI
        GAPI -->|"error"| OAPI
        OAPI -->|"error"| NONE
    end

    subgraph STORE["Knowledge Store (~/.keephive/hive/)"]
        MEM[("Memory<br>30–90d TTL")]
        SOUL[("SOUL.md<br>agent identity")]
        GUIDES[("Guides")]
        RULES[("Rules")]
        LOG[("Daily log")]
        TODOS[("TODOs")]
        PENDING[(".pending-facts")]
        STATS[(".stats.json<br>workflow analytics")]
    end

    subgraph DAEMON["KingBee Daemon (background)"]
        BRIEF["morning briefing"]
        IMPROVE[(".pending-improvements")]
        STALECK["stale-check scan"]
    end

    subgraph CC["Claude Code Data (~/.keephive/usage-data/)"]
        META[("session-meta/<br>msgs, tools, duration,<br>lines, tokens, commits")]
        FACETS[("facets/<br>outcome, friction,<br>satisfaction")]
    end

    subgraph MANUAL["On-demand (CLI · MCP)"]
        REM["hive r · capture"]
        RCL["hive rc · recall"]
        VRF["hive v · verify"]
        REV["hive mem review"]
        RFL["hive rf · reflect"]
        DASH["hive serve · dashboard<br>+ bookmarklet"]
        STCMD["hive stats · hive insights"]
    end

    START -->|reads| STORE
    PC --> LOG
    PC --> PENDING
    PC -->|"soul-update (throttled 1h)"| SOUL
    PC -.->|LLM classify| LLM
    VRF -.->|LLM verify| LLM
    LOG -->|"hive rf · promote"| MEM
    PENDING -->|"hive mem review"| MEM
    MEM -->|"hive v · re-stamp"| MEM
    REM --> LOG
    RCL -.->|searches| STORE
    VRF --> MEM
    REV --> MEM
    RFL --> GUIDES
    DASH -.->|reads| STORE
    DASH -.->|"session analytics"| CC
    STCMD -.->|"session analytics"| CC
    STCMD -.->|"workflow analytics"| STORE
    SEND -.->|".stats.json"| STATS
    DAEMON -->|reads/writes| STORE
    DAEMON --> BRIEF
    DAEMON --> IMPROVE
    DAEMON --> STALECK

    classDef ccdata fill:#1a1a2e,stroke:#4a9eff,stroke-width:2px,color:#4a9eff
    class META,FACETS ccdata
```

### Memory tiers

| Tier             | Path                                 | Purpose                           |
| ---------------- | ------------------------------------ | --------------------------------- |
| Working memory   | `~/.keephive/hive/working/memory.md`   | Core facts, loaded every session  |
| Rules            | `~/.keephive/hive/working/rules.md`    | Behavioral rules for the agent    |
| Knowledge guides | `~/.keephive/hive/knowledge/guides/`   | Deep reference on specific topics |
| Daily logs       | `~/.keephive/hive/daily/YYYY-MM-DD.md` | Append-only session logs          |
| Archive          | `~/.keephive/hive/archive/`            | Old daily logs after gc           |

### Hooks

| Hook             | Trigger               | What it does                                           |
| ---------------- | --------------------- | ------------------------------------------------------ |
| SessionStart     | New session           | Injects memory, rules, TODOs, stale warnings, Agent Identity |
| PreCompact       | Conversation compacts | Extracts insights; triggers throttled `soul-update`    |
| PostToolUse      | After Edit/Write      | Periodic nudge to record decisions                     |
| UserPromptSubmit | User sends prompt     | Periodic nudge, UI queue injection                     |
| Stop             | Agent turn ends       | Increments turn counter, periodic micro-nudge          |
| SessionEnd       | Session terminates    | Finalizes stats; triggers `soul-update` and `self-improve` |
| TaskCompleted    | Task marked done      | Auto-logs DONE entry to daily log                      |

### Use it with other MCP clients

1. `keephive mcp-serve` — starts the stdio server. Leave it running (or supervise it via your agent's process manager).
2. Add an MCP entry to your client. Most configs look like:

   ```json
   {
     "mcpServers": {
       "keephive": {
         "command": "keephive",
         "args": ["mcp-serve"]
       }
     }
   }
   ```

3. Call the tools you need (`hive_recall`, `hive_status`, `hive_todo`, `hive_audit`, etc.). They match the CLI one-for-one, so scripts and agents can share the same workflows.

If your agent exposes lifecycle hooks (session start, prompt submit, completion), map them to the same `hive` commands the Claude integration uses: call `hive remember`/`hive todo` to capture, `hive status` or `hive recall` before prompts, `hive verify` on a schedule. You get the same knowledge loop without depending on Claude Code internals.

---

## Commands

<details>
<summary><b>Full command reference</b> (38 commands)</summary>

| Command                 | Short             | What                                       |
| ----------------------- | ----------------- | ------------------------------------------ |
| **Capture**             |                   |                                            |
| `hive remember "text"`  | `hive r "text"`   | Save to daily log                          |
| `hive t <text>`         |                   | Quick-add a TODO                           |
| `hive note`             | `hive n`          | Multi-slot scratchpad ($EDITOR)            |
| `hive n todo`           | `hive 4 todo`     | Extract action items from a note slot      |
| **Recall**              |                   |                                            |
| `hive status`           | `hive` / `hive s` | Status overview                            |
| `hive recall <query>`   | `hive rc <query>` | Search all tiers (BM25 ranked)             |
| `hive log [date]`       | `hive l`          | View daily log; `hive l summarize` for LLM summary |
| `hive todo`             | `hive td`         | Open TODOs with ages                       |
| `hive todo done <pat>`  |                   | Mark TODO complete                         |
| `hive knowledge`        | `hive k`          | List/view knowledge guides                 |
| `hive prompt`           | `hive p`          | List/use prompt templates                  |
| `hive ps`               |                   | Active sessions, project activity, git state |
| `hive session [mode]`   | `hive go`         | Launch interactive session                 |
| `hive standup`          | `hive su`         | Standup summary with GitHub PR integration |
| `hive stats`            | `hive st`         | Usage statistics                           |
| **Verify**              |                   |                                            |
| `hive verify`           | `hive v`          | Check stale facts against codebase; auto-corrects |
| `hive reflect`          | `hive rf`         | Pattern scan across daily logs             |
| `hive audit`            | `hive a`          | Quality Pulse: 3 perspectives + synthesis  |
| `hive flow`             |                   | **Guided maintenance flow**: one-pass review |
| **Manage**              |                   |                                            |
| `hive mem [rm] <text>`  | `hive m`          | Add/remove working memory facts            |
| `hive rule [rm] <text>` |                   | Add/remove behavioral rules                |
| `hive rule learn`       |                   | Learn rules from /insights friction data   |
| `hive rule review`      |                   | Accept/reject pending rule suggestions     |
| `hive improve review`   |                   | Review pending identity/skill improvements |
| `hive edit <target>`    | `hive e`          | Edit memory, rules, soul, etc.             |
| `hive skill`            | `hive sk`         | Manage skill plugins                       |
| **Maintain**            |                   |                                            |
| `hive daemon [start]`   |                   | **KingBee background daemon** (morning briefs, soul) |
| `hive doctor`           | `hive dr`         | Health check                               |
| `hive gc`               | `hive g`          | Archive old logs                           |
| `hive setup`            |                   | Register hooks and MCP server              |
| `hive update`           | `hive up`         | Upgrade keephive in-place                  |
| **Dashboard**           |                   |                                            |
| `hive serve [port]`     | `hive ws`         | Live web dashboard (localhost:3847)        |
| `hive ui`               |                   | Show / manage UI feedback queue            |

</details>

<details>
<summary><b>Features in depth</b></summary>

#### Dashboard

`hive serve` launches a live web dashboard at localhost:3847 with 6 views:

| View     | Path        | Focus                                                      |
| -------- | ----------- | ---------------------------------------------------------- |
| Home     | `/`         | Full overview: status, log, TODOs, knowledge, memory       |
| Dev      | `/dev`      | Quick reference: TODOs+log, facts, knowledge+memory compact |
| Brain    | `/brain`    | High-density: working memory, rules, TODOs, platform telemetry |
| Know     | `/know`     | Knowledge guides with markdown rendering                   |
| Stats    | `/stats`    | Usage: sparkline, heatmap, streak, command breakdown       |
| Settings | `/settings` | Profile management, agent identity, daemon status          |

Auto-refresh (configurable interval), Cmd+K search, split-pane resizing, CRUD forms (remember, add TODO, mark done, append note), log type filters, and zero external dependencies.

<p align="center">
  <img src="https://raw.githubusercontent.com/joryeugene/keephive/main/assets/dashboard-stats.png" width="700" alt="keephive stats view" />
</p>
<p align="center">
  <img src="https://raw.githubusercontent.com/joryeugene/keephive/main/assets/dashboard-knowledge.png" width="700" alt="keephive knowledge view" />
</p>

**UI feedback loop**: `hive ui-install` generates a bookmarklet and copies it to your clipboard. Paste it as a bookmark URL, then click it on any page to capture an element selector and a note. The feedback is POSTed to the dashboard server, queued in `.ui-queue`, and automatically injected into your next Claude Code prompt via the UserPromptSubmit hook. No copy-paste required.

#### Log Summarize

`hive l summarize` pipes today's log entries to claude-haiku and prints 3-5 bullet-point highlights. Useful after long sessions before compaction.

#### Smart Recall

`hive rc <query>` uses an SQLite FTS5 index over all daily logs and the archive for ranked full-text search. Run `hive gc` to rebuild the index. Falls back to grep if the index is absent.

#### Guide front matter

Knowledge guides support optional YAML front matter for controlling injection:

| Field | Effect |
|-------|--------|
| `tags: [tag1, tag2]` | Matched against project name for auto-injection |
| `projects: [proj1]` | Matched against project name for auto-injection |
| `paths: ["/path/pattern"]` | Matched against working directory for auto-injection |
| `always: true` | Injected into every session regardless of project (opt-in, no guides ship with this) |

Guides without front matter match only by filename (project name as substring). The `always: true` flag is strictly opt-in and costs one of the three guide slots per session, so use it only for guides that genuinely apply to every project.

#### Notes

`hive n` is a multi-slot scratchpad. Each slot persists across sessions, auto-copies to clipboard on save, and can be initialized from a prompt template (`hive n <template>`). Use `hive n.2` or `hive 2` to switch to slot 2 and open it in `$EDITOR`.

`hive n todo` (or `hive 4 todo` for slot 4) scans the active slot for action items. Both plain text lines and bullet points from a `## todo` section become candidates; items over 120 characters are skipped as observations. For a single item, you get a yes/no prompt. For multiple items, your `$EDITOR` opens with the candidates — delete lines you don't want, save and quit to confirm.

`hive 4 "text"` appends text directly to slot 4 without opening an editor. Use bare-digit commands with a quoted string to capture quick notes mid-session.

#### Edit

`hive e <target>` opens files in `$EDITOR`. Targets: memory, rules, todo (with diff-on-save), CLAUDE.md, settings, daily log, notes. Run `hive e` with no arguments to see all targets.

#### Sessions

`hive go` launches an interactive Claude session with your full keephive context pre-loaded (memory, rules, TODOs, stale warnings, matching guides). The SessionStart hook detects the launch and skips re-injection to avoid duplication.

| Command                 | What                                           |
| ----------------------- | ---------------------------------------------- |
| `hive go`               | General session with full memory and warnings  |
| `hive session todo`     | Walk through open TODOs one by one             |
| `hive session verify`   | Check stale facts against the codebase         |
| `hive session learn`    | Active recall quiz on recent decisions         |
| `hive session reflect`  | Pattern discovery from daily logs              |
| `hive session <prompt>` | Load a custom prompt from `knowledge/prompts/` |

Custom prompts resolve by prefix, so `hive go pr-re` finds `pr-review-git-staged-diff-analysis.md`. You can also pipe content in: `cat api-spec.yaml | hive go review`. Pass `-c` to continue the last conversation or `-r <id>` to resume a specific session.

#### Reflect

`hive rf` scans daily logs for recurring patterns across multiple days. When it finds a theme, `hive rf draft <topic>` generates a knowledge guide from the matching entries. This is how scattered daily notes become structured reference material.

#### Audit

`hive a` runs three parallel LLM analyses on your memory state (fact accuracy, data hygiene, strategic gaps), then synthesizes them into a quality score with actionable suggestions.

#### Standup

`hive su` generates a standup summary from recent daily log activity and optionally includes GitHub PR data.

#### KingBee (Daemon)

`hive daemon start` launches a background process that manages persistent agent identity and automated maintenance.

- **Agent Identity**: Manages `SOUL.md`, a cross-project summary of the agent's specialized skills, patterns, and evolving personality.
- **Morning Briefing**: Your first session of the day receives a synthesized briefing of pending tasks and recent activity.
- **Self-Improvement**: The daemon scans logs to propose new skills, behavioral rules, or task optimizations, queued for your review.
- **Stale Check**: Automatically identifies facts that haven't been verified recently.

#### Flow

`hive flow` is a guided maintenance command that drains all pending queues in one pass. It walks you through:
1. **Triage**: Overview of pending items.
2. **Fact Review**: Graduate auto-captured insights to working memory.
3. **Rule Review**: Accept or reject behavioral rule suggestions.
4. **Improvement Review**: Review self-improvement proposals from KingBee.
5. **Verify**: Run a full verification of stale facts against the codebase.

#### Improve

`hive improve review` opens an interactive TUI to review proposals from the KingBee daemon. Improvements can be:
- **Skills**: New specialized capabilities or tool patterns.
- **Rules**: Behavioral nudges to avoid recurring friction.
- **Tasks**: Suggested optimizations for your daily workflow.
- **Edits**: Direct improvements to knowledge guides or configuration.

#### Stats

`hive st` shows usage statistics with per-project breakdown, session streaks, and activity sparklines. The dashboard stats view (`/stats`) adds a 14-day sparkline with day-of-week labels and weekend shading, an hourly heatmap, and a sortable command breakdown table.

#### Prompts

`hive p` lists reusable prompt templates stored in `knowledge/prompts/`. Use them to start notes (`hive n <template>`) or launch custom sessions (`hive session <template>`).

</details>

<details>
<summary><b>MCP tools</b></summary>

All commands are also available as MCP tools for Claude Code to call directly:

`hive_remember`, `hive_recall`, `hive_status`, `hive_todo`, `hive_todo_done`, `hive_knowledge`, `hive_knowledge_write`, `hive_prompt`, `hive_prompt_write`, `hive_mem`, `hive_rule`, `hive_log`, `hive_audit`, `hive_recurring`, `hive_stats`, `hive_fts_search`, `hive_standup`, `hive_ps`

</details>

---

## Configuration

<details>
<summary><b>Environment variables</b></summary>

| Variable              | Default            | Description                                                       |
| --------------------- | ------------------ | ----------------------------------------------------------------- |
| `HIVE_HOME`           | `~/.keephive/hive` | Data directory                                                    |
| `HIVE_STALE_DAYS`     | `30`               | Days before a fact is flagged stale                               |
| `HIVE_CAPTURE_BUDGET` | `4000`             | Characters to extract from transcripts                            |
| `ANTHROPIC_API_KEY`   | (unset)            | Enables Anthropic API backend inside Claude Code sessions         |
| `OPENAI_API_KEY`      | (unset)            | Enables OpenAI backend fallback inside Claude Code sessions       |
| `GEMINI_API_KEY`      | (unset)            | Enables Gemini API backend fallback inside Claude Code sessions   |
| `NO_COLOR`            | (unset)            | Disable terminal colors                                           |

</details>

---

## LLM features

> [!IMPORTANT]
> keephive calls `claude -p` for LLM features. If you're on a Claude Pro or Max subscription, these calls are included at no extra cost (they count against your plan's normal usage limits). If you use Claude Code with API billing, `claude -p` calls consume your API tokens. `ANTHROPIC_API_KEY` is never checked from a terminal or a hook.

The API path exists for one specific case: running LLM commands (`hive a`, `hive v`, etc.) _inside_ a Claude Code session rather than from a separate terminal. That is the only time `ANTHROPIC_API_KEY` is consulted.

<details>
<summary><b>Billing tiers and LLM-powered commands</b></summary>

### Multi-backend routing

keephive uses a priority-ordered backend chain. The first available backend wins:

| Priority | Backend | When active | Cost |
|----------|---------|-------------|------|
| 10 | `claude -p` CLI | Terminal or hooks (default, always) | Included with Pro/Max; API tokens if on API billing |
| 20 | Anthropic API | Inside Claude Code + `ANTHROPIC_API_KEY` | Paid — per-token |
| 25 | Gemini API | `GEMINI_API_KEY` set | Paid — per-token |
| 30 | OpenAI API | `OPENAI_API_KEY` set | Paid — per-token |
| 99 | None (offline) | Always — last resort | Free, no LLM output |

If a backend fails with a transient error, the router automatically tries the next one. **Timeouts are non-retriable** — a `BackendTimeoutError` propagates immediately rather than silently changing model behavior by switching to a different LLM.

Hooks (PreCompact, etc.) run without the `CLAUDECODE` environment variable, so they always take the `claude -p` subprocess path regardless of whether any API key is present in your shell.

### LLM-powered commands

| Command | Model | When to use |
|---------|-------|-------------|
| `hive a` (audit) | 3× haiku + 1× sonnet | Intentional quality check |
| `hive v` (verify) | sonnet + tools, multi-turn | Validating stale facts |
| `hive rf analyze/draft` | haiku | Pattern discovery |
| `hive su` (standup) | haiku | Daily standup generation |
| `hive l summarize` | haiku | End-of-session summary |
| `hive dr` (doctor) | haiku, optional | Duplicate TODO detection |
| PreCompact hook | haiku | Automatic on compaction |

`hive a` and `hive v` are the heavyweight operations. Use them intentionally.

### Free commands (no LLM)

`hive r`, `hive rc`, `hive s`, `hive todo`, `hive t`, `hive m`, `hive rule`, `hive e`, `hive n`, `hive k`, `hive p`, `hive st`, `hive l` (without `summarize`), `hive gc`, `hive sk`, and all hooks except PreCompact (SessionStart, PostToolUse, UserPromptSubmit, Stop, SessionEnd, TaskCompleted).

### Disable automatic LLM calls

> [!NOTE]
> Set `HIVE_SKIP_LLM=1` to skip the PreCompact hook's extraction step. SessionStart never calls an LLM.

</details>

---

## Development

```bash
uv run pytest                          # all tests
uv run pytest -m llm -v -o "addopts="  # LLM E2E tests (slow, real API calls)
uv run pytest -x                       # stop on first failure
```

See [CLAUDE.md](CLAUDE.md) for architecture details.

## License

MIT
