# Agora Code

> Use agora-code memory tools — inject session context, learn findings, recall past work, checkpoint progress, and summarize large files Use when this capability is needed.

- Skill: `tomevault-io/agora-code` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/agora-code`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/agora-code/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/agora-code

---


> **STOP — before you do anything else:**
> Run `agora-code summarize <file>` before reading ANY file over ~50 lines.
> Do NOT use Read or an Explore subagent on a large file without summarizing first.
> **This is not optional. The Explore subagent is blocked in agora-code projects.**

agora-code gives you persistent memory across sessions. Hooks handle most things automatically, but **you must follow the rules below** — they are not optional.

## Your rules (always follow these)

1. **Before reading any file over ~50 lines** — run `agora-code summarize <file>` first. Do not use the Read tool or an Explore subagent on a large file without summarizing first. This is mandatory, not optional.
2. **At session start** — run `agora-code inject` to load prior context (checkpoints, learnings, git state, symbol index).
3. **When done with a task** — run `agora-code complete --summary "..."` to archive the session.
4. **Always** run `agora-code status -p` (not `status`) to see per-project stats.
5. **Do not ask the user to set a goal** — infer it from what they're working on.

## What the hooks handle automatically (no action needed)

| Hook | Event | Does |
|---|---|---|
| `pre-agent.sh` | PreToolUse(Agent) | **Blocks Explore subagent** — exit 2 prevents launch |
| `pre-read.sh` | PreToolUse(Read) | Intercepts large files — auto-summarizes before Claude reads |
| `on-read.sh` | PostToolUse(Read) | Indexes symbols + code blocks into DB |
| `on-grep.sh` | PostToolUse(Grep) | Indexes files matched by grep into DB |
| `on-edit.sh` | PostToolUse(Write/Edit) | Re-indexes symbols, tracks diff |
| `on-bash.sh` | PostToolUse(Bash) | Tags committed files with SHA on `git commit` |
| `on-prompt.sh` | UserPromptSubmit | Auto-sets goal, recalls relevant learnings |
| `on-stop.sh` | Stop | Parses transcript → structured checkpoint |

PostCompact re-injects context automatically after context compaction.

## Session lifecycle

```
SessionStart  → agora-code inject                        # load prior context
Working       → agora-code summarize <file> FIRST        # ← MANDATORY before any large file
Step done     → agora-code checkpoint --goal "..."        # optional mid-task save
All done      → agora-code complete --summary "..."       # archive session
```

## Manual commands reference

| Command | When to use |
|---|---|
| `agora-code inject` | Load prior session context |
| `agora-code summarize <file>` | **Before reading any file over ~50 lines** |
| `agora-code learn "<text>"` | Force-save a specific finding right now |
| `agora-code recall "<query>"` | Search past findings for a topic |
| `agora-code checkpoint --goal "..."` | Save progress mid-task |
| `agora-code status -p` | Check session and DB stats for this project |
| `agora-code complete --summary "..."` | Archive session when done |

## inject output format

`agora-code inject` outputs ~300 tokens of structured context:

```
LAST CHECKPOINT
  goal / decisions / next_steps / blockers / files / branch + commit

LEARNINGS
  recent findings tagged by type (decision → / blocker ! / next » / finding ·)

GIT LOG
  last 6 commits

UNCOMMITTED
  dirty files

SYMBOL INDEX
  function:line for dirty files (avoids re-reading them)
```

---
> Source: [thebnbrkr/agora-code](https://github.com/thebnbrkr/agora-code) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-24 -->