aspens for AI coding teams

Open source for Claude Code and Codex

Give your coding agents the context your repo already has.

Aspens scans your repo, generates compact agent instructions, and keeps them current as the code changes.

npx aspens install

Built for real repositories, not toy prompts

Aspens maps your repo, identifies the important modules, and generates the structure your agents need to navigate the codebase consistently.

Without aspens

Every session starts blind

Agents miss architecture and waste tokens rediscovering context every run.

With aspens

Context is generated once and maintained

Durable instructions, domain skills, and hooks that stay aligned with the code.

Repo-aware by default

Detects domains, import hubs, and high-churn areas automatically.

Compact, usable outputs

Short skills and instructions agents can actually use.

Works across targets

Generate context for Claude Code and Codex from one scan.

Stays current over time

Post-commit sync updates only the skills that changed.

Architecture of the pipeline

aspens doc init

Deterministic scan and analysis

Feeds scan + context + import graph into LLM

LLM output parse

Skill writer writes .claude/ files

aspens doc sync

Incrementally updates from git diffs

aspens doc impact

Checks for freshness / drift

What `doc init` writes

Always

CLAUDE.md and skills

CLAUDE.md root instructions file
.claude/skills/<name>/skill.md generated skill files (one per domain/topic)
.claude/skills/skill-rules.json activation rules for skills
.claude/settings.json hooks config (merges with existing, backs up to .bak)
.aspens.json project config (targets, backend)

Hooks

.claude/hooks/skill-activation-prompt.sh + .mjs loads relevant skills per task
.claude/hooks/graph-context-prompt.sh + .mjs injects import graph context
.claude/hooks/post-tool-use-tracker.sh tracks domain file access

Graph artifacts

.claude/.graph.json, .code-map.md, .index.json import graph cache

If Codex target —target codex|all

AGENTS.md / .agents/AGENTS.md Codex instructions
.agents/skills/*.md Codex skill files

With —recommended

.claude/agents/*.md bundled agent templates (not customized — need to also run aspens customize agents after)
.git/hooks/post-commit auto-runs aspens doc sync to keep context fresh on every commit
.claude/hooks/save-tokens-*.sh, .claude/commands/*.md, .aspens/sessions/ reduces token usage across Claude Code sessions

Docs and guides to get you started

Quick Start How It Works Skills doc init

FAQ

Does aspens require hosting or any third party services?

No. Aspens is an open-source CLI. You use your own configured assistant for generation commands.

Which assistants does it support today?

Claude Code and Codex are first-class targets. Aspens can generate target-specific repo context for both from a shared scan of the codebase.

What parts of Aspens use an LLM?

aspens scan is deterministic. Commands that generate or refresh context, such as doc init and doc sync, use your configured coding-assistant backend.

Who is Aspens for?

For anyone using AI coding tools regularly. The value shows up even for a solo maintainer if you want the repo context to persist across sessions.

Can I just try it without messing my setup or generating files?

Yes. Run any generation command with —dry-run to preview what would be written without touching your repo.

Can it modify my source code?

No. All writes are restricted to .claude/, .agents/, instruction files (CLAUDE.md/AGENTS.md), and .aspens.json. A path sanitizer enforces this — it cannot touch your application code.

Is the generated output committed to my repo?

That’s up to you. Skills and instruction files are regular files you can review, edit, or gitignore. Graph artifacts are auto-gitignored by default.

Is it open source?

Yes. You can audit the full codebase on GitHub before running it.