Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIMuseMuseDotsDots+21 more

    codebase chatter

    1

    Index and search Python codebases with symbol-level precision, call graph expansion, and exact line citations.

    Free

    Security scanned
    codebase chatter

    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.py in sub/.gitignore only match sub/only_here.py.
    • Directories get a trailing /, so directory-only patterns like build/ match them.
    • The deepest .gitignore wins. The list runs from the root .gitignore down to the deepest one. A spec that has no opinion returns None and is skipped, so the last spec that does match decides. Within a single file, GitIgnoreSpec handles last-match-wins and !negation.
    • Excluded directories are dropped entirely. A !pattern can'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 .gitignore files are read. .git/info/exclude, global excludes (core.excludesFile) and any .gitignore above the repo root are ignored.
    • The index can lag behind your files. These citations come from the chatter index, which only updates when chatter index is 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

    Setup in 3 steps

    1. Install Codebase Chatter from the repo (see its README).
    2. Index your project: chatter index /path/to/your/repo
    3. 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. 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. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 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

    GitHub
    Hugging Face
    Python 3.11+
    Codebase Chatter (free on GitHub)
    Claude Code
    Python

    Permissions

    Terminal / Shell
    Read Files
    Write Files
    Network Access

    Allowed Hosts

    github.com
    huggingface.co

    File Scopes

    **/*.py
    .chatter/**
    ~/.claude.json

    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.

    Listed1 day ago

    What's inside

    Frequently Asked Questions

    Uploading files only works for small projects and leaves the model to find the right code itself. Codebase Chatter indexes your repo by function, method and class and adds call-graph links, so your agent retrieves just the relevant code, even across many files. The skill tells the agent to read that code before answering, cite every claim as path:start-end, and say so when the answer isn’t in the code. That makes guessing much rarer and easy to check, though no tool can rule it out completely.

    Not yet. The indexer parses Python only, splitting code into functions, methods, classes and module-level code. For other languages the skill tells the agent to say so and fall back to reading files normally.

    The skill is a SKILL.md file that teaches your agent how to use the Codebase Chatter MCP server. It works with agents that support both SKILL.md skills and stdio MCP servers. It has been tested with Claude Code; other compatible agents should work but haven’t been verified.

    No. Indexing, embeddings and search all run on your machine, and Codebase Chatter sends nothing anywhere. But the code your agent retrieves is shown to the agent’s AI model, as with anything else you ask it about, so it goes wherever your agent sends its requests (for Claude Code, to Anthropic). The optional ask tool uses a local model instead.

    No. Re-run chatter index after changes. Re-indexing is incremental: only functions that changed are re-embedded, so it’s quick.

    The package contains the skill itself: a SKILL.md with setup steps, a search strategy for each type of question, citation and “say when it’s not there” rules, known limitations and safety guidance. The Codebase Chatter tool it uses is free and open source, installed separately from https://github.com/Manav250305/codebase-chatter.

    No. Indexing and search run on an ordinary CPU, and the embedding model is small (~130 MB). The optional ask tool runs a larger local model and works best on Apple Silicon or a GPU, but the default tools don’t need it.

    Yes, but each registered server searches one repo. Index each project and register a server for it under its own name (for example chatter-api, chatter-web).

    The skill tells the agent to say so plainly and list what it searched, rather than filling the gap from general knowledge.

    New in Code Quality & Review