CodeSense

Automatic context files for your codebase — so LLMs understand your repo without manual documentation.

CodeSense scans your codebase via AST parsing and generates structured context files inside .codesense/. A pre-commit hook keeps them in sync automatically — every commit includes fresh context alongside your code changes. Zero config, zero maintenance.

Why it matters

Without CodeSense, every time you ask an LLM about your codebase it has to search through files, read source code, and piece together the architecture from scratch. That means:

• More tool calls — the LLM reads file after file to answer a single question
• More tokens — redundant context gets loaded on every conversation
• Slower responses — more work before it can actually help you

With CodeSense, the LLM reads one small YAML file and immediately knows what a module does, what it exports, and how it connects to the rest of the codebase. Questions that used to take 10+ file reads now take 1.

In practice: fewer tool calls, lower token usage, faster and more accurate answers.

How it works

codesense init          # scan repo → generate .codesense/ → install pre-commit hook
git commit -m "..."     # hook fires → context auto-updates → included in same commit

Any LLM tool (Claude Code, Cursor, Copilot) reads .codesense/ and immediately understands your repo's structure, modules, and APIs — without searching through files.

Installation

npm install -g codesense-cli

Quick Start

cd your-project
codesense init

That's it. CodeSense will:

1. Scan all TypeScript and Python files
2. Generate .codesense/ARCHITECTURE.md, interfaces.yaml, and per-directory context files
3. Install a pre-commit hook so context stays current
4. Write CLAUDE.md (and .cursorrules if Cursor is detected)

Commands

codesense init

Full setup. Run once per repo.

codesense init              # scan + generate + install hook
codesense init --no-hook    # skip pre-commit hook
codesense init --force      # re-initialize existing setup

codesense update

Refresh context files. Called automatically by the pre-commit hook.

codesense update            # diff-aware: only re-process changed files
codesense update --full     # force complete re-scan
codesense update --staged   # pre-commit mode (staged files only)

codesense status

See what CodeSense knows about your repo.

codesense status

📊 CodeSense Status

  Files scanned:  47
  Last scan:      2m ago
  Context files:  12

  Pre-commit hook: ✓ installed

  LLM integrations:
    claude   ✓ CLAUDE.md
    cursor   ✓ .cursorrules

codesense integrate

Generate or refresh LLM tool config files.

codesense integrate           # auto-detect and generate all
codesense integrate --claude  # CLAUDE.md only
codesense integrate --cursor  # .cursorrules only
codesense integrate --copilot # .github/copilot-instructions.md only

What gets generated

your-repo/
├── .codesense/
│   ├── ARCHITECTURE.md        # tech stack, entry points, module map
│   ├── interfaces.yaml        # detected REST endpoints and public APIs
│   └── context/
│       ├── src--routes.yaml   # context for src/routes/
│       ├── src--services.yaml # context for src/services/
│       └── src--models.yaml   # context for src/models/
├── CLAUDE.md                  # points LLMs to .codesense/
└── .cursorrules               # same, for Cursor

Context files are 20-50 lines each. Total .codesense/ footprint stays under 100KB even for large repos.

Should I commit .codesense/?

Yes, in most projects. Committing .codesense/ means every developer and every AI tool gets fresh context after git pull. The pre-commit hook keeps it in sync automatically.

If you prefer not to commit it, add .codesense/ to .gitignore. Context files still update on disk on every commit — they just won't be tracked.

Languages supported

• TypeScript / JavaScript
• Python

More languages coming.

Existing commands

CodeSense also includes AI-powered documentation tools (require Ollama):

codesense explain auth.ts     # explain a file with AI
codesense scan ./src          # analyze code and show stats
codesense docs ./src          # generate full documentation
codesense readme              # generate a project README
codesense agents              # generate AGENTS.md

License

MIT — Jashan Rahal