intel

a project intelligence agent for claude code that learns your codebase and never forgets

---

you open a terminal, type claude, and ask it how the auth module works

claude doesn't know, so it globs for files, reads your src directory, greps for imports, reads config files, traces the dependency chain, 4 minutes later it gives you an answer

tomorrow you ask the same question, it does the whole thing again, from scratch, because it forgot everything when the session ended

or worse, 40 minutes into a session context compacts and claude loses all the architectural understanding it built up, starts re-reading the same files, re-discovering the same patterns, re-learning that your test command fails without NODE_ENV=test

intel fixes this, it is a subagent with persistent memory that builds deep project knowledge and keeps it forever, every session it gets smarter, every question it answers gets saved, every pattern it notices gets recorded, context compaction cannot touch it because the knowledge lives outside the context window

git clone https://github.com/chiefautism/claude-intel.git
cd claude-intel
bash install.sh

that's it, claude now has a brain that survives between sessions

---

the details

the problem

claude code has no long-term project memory, every session starts from zero, every compaction erases hard-won understanding, claude re-reads the same files hundreds of times across sessions, re-discovers the same architecture, re-learns the same gotchas, this is the single biggest source of wasted tokens and wasted time

auto-memory exists but it saves random notes in an unstructured file, CLAUDE.md is static and manual, warm-start gives you git state and stack detection but not architectural understanding, nothing actually learns your codebase and remembers it

the fix

two components that work together:

a subagent (~/.claude/agents/intel.md) with persistent project-scoped memory that builds and maintains structured knowledge files about your codebase, it runs on haiku so it costs pennies, it uses memory: project so each project gets its own knowledge base that persists across sessions

a hook (~/.claude/scripts/posttool-feed.sh) that silently logs every file edit and command execution as JSONL events, giving the agent a feed of what happened in the session without burning context tokens

on first run the agent deep-scans your project and writes everything it learns to structured memory files, on every run after that it reads its memory instantly, checks the event feed for new activity, answers your question, and updates its knowledge if it learned something new

the agent maintains these knowledge files:

• architecture.md — how the codebase is organized, key directories, entry points, module boundaries, data flow
• commands.md — how to build, test, lint, run, deploy, exact commands that work with flags and gotchas
• patterns.md — coding conventions, naming patterns, common abstractions, preferred libraries
• gotchas.md — things that are surprising, broken, or non-obvious, traps that waste time
• decisions.md — key technical decisions, why X was chosen over Y, migration states, known TODOs

install

requires jq, that is the only dependency

git clone https://github.com/chiefautism/claude-intel.git
cd claude-intel
bash install.sh

this does three things:

1. copies intel.md to ~/.claude/agents/
2. copies posttool-feed.sh to ~/.claude/scripts/
3. adds a PostToolUse hook to ~/.claude/settings.json

no databases, no http servers, no background processes, it uses the subagent persistent memory and hook system that already exist in claude code

usage

it is automatic, claude delegates to @intel when it needs project context

you can also ask directly:

ask intel how this project is structured

what does intel know about our test setup

have intel check what commands work in this project

to force a full rescan after a major refactor:

ask intel to rescan this project

the PostToolUse hook starts collecting data immediately, no action required, every file edit and bash command gets logged silently to the event feed

the event feed

the hook logs events to .claude/agent-memory/intel/feed.jsonl in your project:

{"ts":1709876543,"tool":"Edit","file":"src/api/auth.ts"}
{"ts":1709876600,"tool":"Bash","cmd":"npm test","exit":1,"err":"FAIL src/api/auth.test.ts"}
{"ts":1709876650,"tool":"Bash","cmd":"npm run build"}

only Edit, Write, and Bash are logged, Read and Grep are excluded because they are too noisy and carry no signal about what changed, the feed auto-rotates at 500 lines so it never grows unbounded

the agent reads this feed to notice what files are being worked on, which commands fail, and what patterns emerge, without anyone having to tell it

how it compounds

session	what happens
1	cold start, agent scans project, writes memory files, takes 10-15 seconds
2	instant answers from memory, learns new things from the event feed
3+	deep project knowledge available immediately, notices new patterns
after compaction	knowledge survives because it lives in persistent memory, not context

this is the key difference from everything else, a CLAUDE.md is static, an MCP server is stateless, auto-memory is unstructured, this learns and compounds

example

first invocation on a next.js project, the agent scans and writes:

# architecture.md

- monorepo: app/ (next.js frontend), packages/api (express backend), packages/shared (types)
- app uses app router, layouts in app/(dashboard)/layout.tsx
- auth: next-auth v5, providers in app/api/auth/[...nextauth]/route.ts
- database: prisma, schema in packages/api/prisma/schema.prisma
- state: zustand stores in app/stores/, server state via tanstack query

# commands.md

- `pnpm dev` — starts both frontend (port 3000) and backend (port 4000) via turbo
- `pnpm test` — runs vitest, needs DATABASE_URL set or tests fail with connection error
- `pnpm build` — turbo build, frontend first then api
- `pnpm db:push` — push prisma schema changes (dev only, use db:migrate for prod)
- `pnpm lint` — eslint + prettier check, auto-fix with `pnpm lint:fix`

# gotchas.md

- prisma client must be regenerated after schema changes: `pnpm db:generate`
- next.js middleware.ts at root catches all routes, check matcher config before adding routes
- env vars need NEXT_PUBLIC_ prefix for client-side access, common source of "undefined" bugs
- test database is separate, set TEST_DATABASE_URL or tests hit production db

second session, you ask "how do i add a new api endpoint" and the agent answers instantly from memory without reading a single file

files

~/.claude/agents/intel.md                         - subagent definition
~/.claude/scripts/posttool-feed.sh                - PostToolUse hook script
~/.claude/settings.json                           - hook registration (PostToolUse)
<project>/.claude/agent-memory/intel/             - persistent memory (per-project, auto-created)
<project>/.claude/agent-memory/intel/feed.jsonl   - event feed (auto-created)

uninstall

remove the PostToolUse hook entry from ~/.claude/settings.json, then delete the agent and script:

rm ~/.claude/agents/intel.md
rm ~/.claude/scripts/posttool-feed.sh

per-project memory lives in .claude/agent-memory/intel/ inside each project, delete those directories if you want to clear learned knowledge

why this exists

subagent persistent memory shipped in claude code v2.1.33, one month ago, almost nobody is using it yet, it is the most underexploited feature in the entire ecosystem

100+ subagent repos exist on github, none of them use persistent memory, claude-mem exists but it requires sqlite, chroma, and an http server, code-index-mcp exists but it is a stateless file indexer, warm-start exists but it gives you git state not project understanding

what was missing is a lightweight agent that actually learns your codebase over time, accumulates structured knowledge, and makes it available instantly in every future session, the kind of institutional memory that makes the difference between a new hire and a senior engineer who has worked on the project for a year

now it exists, two files, zero dependencies beyond jq, and it gets smarter every time you use it