- Home
- Skills
- Code Quality & Review
- codebase chatter
Works with the AI Agents you already use
codebase chatter
Index and search Python codebases with symbol-level precision, call graph expansion, and exact line citations.
Free
codebase chatter
Example session with this skill installed
Using the chatter tools on my codebase-chatter repo, find where indexing decides which files to skip (for example macOS "._" files and .gitignore rules) and explain how it works. Cite the code.
- Read your context and instructions
- Compiled the codebase chatter
I found it with the chatter tools. All of the filtering happens in one generator, iter_source_files. A second check runs later, when each file is read.
Where it happens
build_index gets every file it indexes from iter_source_files (src/chatter/index.py:393-519):
for path in iter_source_files(repo_path):
files += 1
rel = path.relative_to(repo_path).as_posix()
text = read_source(path, label=rel, max_bytes=config.max_file_bytes)
Step 1: iter_source_files (src/chatter/index.py:234-267)
It uses os.walk(root, followlinks=False) to walk the repo and prunes directories as it goes:
for name in sorted(dirnames):
child = current / name
if name in SKIP_DIRS or child.is_symlink() or _ignored(active, child, is_dir=True):
continue
kept.append(name)
active_by_dir[child] = active
dirnames[:] = kept
Then it filters files
for name in sorted(filenames):
path = current / name
if path.suffix not in suffixes or name.startswith("._") or path.is_symlink():
continue
if not _ignored(active, path, is_dir=False):
yield path
Fixed rules. These constants are defined at the top of src/chatter/index.py (module chunk index.py:1-61):
SKIP_DIRS = frozenset(
{".git", ".hg", ".svn", ".venv", "venv", "node_modules", "__pycache__", INDEX_DIRNAME}
)
SOURCE_SUFFIXES = frozenset({".py"})
Directories: anything named in SKIP_DIRS is skipped at any depth. That list includes .chatter, the index's own folder. Symlinked directories are skipped too. Because pruned names are removed from dirnames in place, os.walk never goes inside them.
Files: only .py files are kept. Files whose names start with ._ are dropped. These are the AppleDouble metadata files macOS creates on exFAT/FAT drives. Symlinked files are also dropped, which matches how git stores symlinks and avoids loops and duplicates (per the docstring).
- The
._check applies only to files. A directory whose name starts with._would still be walked.
.gitignore rules. Each directory reads its own .gitignore through _load_gitignore (index.py:270-275):
def _load_gitignore(path: Path) -> pathspec.GitIgnoreSpec | None:
try:
lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
except OSError:
return None
return pathspec.GitIgnoreSpec.from_lines(lines)
If the directory has no .gitignore, or it can't be read, the function returns None and nothing is added. Otherwise (directory, spec) is appended to that directory's active list. Each kept subdirectory is stored in active_by_dir with that list, so it inherits every .gitignore above it. The child copies the list with list(...) when it pops it, so sibling directories never share each other's additions.
_ignored (index.py:278-287) decides each path:
for base, spec in active:
rel = path.relative_to(base).as_posix() + ("/" if is_dir else "")
verdict = spec.check_file(rel).include
if verdict is not None:
ignored = verdict
return ignored
- Paths are relative to each
.gitignore's own directory. That means anchored patterns like/only_here.pyinsub/.gitignoreonly matchsub/only_here.py. - Directories get a trailing
/, so directory-only patterns likebuild/match them. - The deepest
.gitignorewins. The list runs from the root.gitignoredown to the deepest one. A spec that has no opinion returnsNoneand is skipped, so the last spec that does match decides. Within a single file,GitIgnoreSpechandles last-match-wins and!negation. - Excluded directories are dropped entirely. A
!patterncan't bring back a file inside a directory that was already excluded. Git behaves the same way.
Step 2: read_source (src/chatter/extract.py:143-159)
Files that pass step 1 can still produce no chunks. read_source returns None in three cases:
- the file is larger than
max_file_bytes - the file can't be read (
OSError) - the file contains a NUL byte, so it's treated as binary
In each case build_index gets no chunks for that file. It has already counted the file in files += 1, though, so the "files" number in IndexStats includes files that were skipped at this step.
The test that covers it
tests/test_index.py:174-204 builds a repo containing build/, *_generated.py with !keep_generated.py, a nested sub/.gitignore with local_*.py and /only_here.py, the folders .git, .venv, node_modules, __pycache__ and venv, plus a ._a.py file. It expects exactly these files to be indexed:
a.py, keep_generated.py, other/local_x.py, sub/b.py, sub/deeper/only_here.py
That result shows three of the rules above: nested patterns stay local to their directory (other/local_x.py is kept), anchoring works (sub/deeper/only_here.py is kept), and negation works.
Limits
- Only
.gitignorefiles are read..git/info/exclude, global excludes (core.excludesFile) and any.gitignoreabove the repo root are ignored. - The index can lag behind your files. These citations come from the chatter index, which only updates when
chatter indexis re-run.
Connects securely to your tools. The creator never sees your data.
About this skill
What it does
This skill teaches your agent to answer questions about a Python codebase from the code itself, with every claim cited as path:start-end. It drives the open-source Codebase Chatter MCP server, which indexes your repo by symbol (functions, methods, classes) and adds call-graph expansion so multi-file flows are found too.
Problems it solves
- Agents guess how code works, or answer from general knowledge of a library instead of your copy of it.
- Plain text search misses code that uses different words than your question.
- Questions about flows ("how does a request reach the database?") need several files, and one-shot search finds only one.
How it works
- Chooses a search strategy for each kind of question: exact names, behavior, locations, or multi-step flows.
- Reads the full code before making a claim, and cites every claim.
- Says plainly when the code doesn't contain the answer, instead of filling the gap.
- Treats repository content as data, so instructions hidden in comments are ignored.
Requirements
- Codebase Chatter (free, open source): https://github.com/Manav250305/codebase-chatter
- Python repositories only, for now
- Everything runs locally. The index and embedding model stay on your machine.
Setup in 3 steps
- Install Codebase Chatter from the repo (see its README).
- Index your project:
chatter index /path/to/your/repo - Register the server with your agent, e.g. for Claude Code:
claude mcp add --transport stdio --scope user chatter -- /path/to/.venv/bin/chatter mcp --path /path/to/your/repo
Measured, not assumed
The retrieval defaults were chosen by an evaluation with held-out questions, not by intuition. The method and results are in the repo's README.
Python files only. The index updates only when you re-run chatter index (incremental, so re-runs are fast). Each registered server searches one repo; add another server for each extra project. Exact identifier lookups can rank lower in the default dense mode; the skill switches to fused or bm25 mode for those. Comments separated from a function by a blank line aren't indexed. The optional ask tool runs a local 4B model and needs several GB of RAM (about 4 GB on Apple Silicon); the default search tools don't use it.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before any payment.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Free forever
No account required to browse
Trust & safety
Security scan
Security scan passed 1 day ago
- Free with an Agensi account
Requires
Permissions
Allowed Hosts
File Scopes
Shell, file writes and network are used only during one-time setup, and only after the user agrees: installing Codebase Chatter from GitHub, building the local index (written to the repo's .chatter/ folder; the first run downloads an embedding model from Hugging Face), and registering the MCP server in the agent's config. Answering questions is read-only: the MCP server never modifies the repo or the index, and no code leaves the machine.