Fledgling

MCP tools that help AI agents get their bearings in a codebase, powered by DuckDB.

curl -sL https://raw.githubusercontent.com/teaguesterling/fledgling/main/sql/install-fledgling.sql | duckdb

Run from your project root. Creates three files and you're done.

Requires duckdb CLI (v1.4+). Install: brew install duckdb or see duckdb.org.

What you get

.fledgling-init.sql — self-contained DuckDB init with all modules
.fledgling-help.md — skill guide for the agent
.mcp.json — MCP server config (merged with existing)

MCP Tools

These tools are exposed directly to the agent via MCP.

ReadLinesFile content with line ranges, context, and match filtering

FindDefinitionsAST-based search for functions, classes, variables (27 languages)

CodeStructureTop-level structural overview of source files

GitDiffSummaryFile-level change summary between revisions

GitShowFile content at a specific git revision

MDSectionRead markdown sections by ID

ChatSessionsBrowse Claude Code conversation sessions

ChatSearchFull-text search across conversations

ChatToolUsageTool usage frequency analysis

ChatDetailDeep view of a single session

HelpBuilt-in skill guide for the agent

FindInASTSearch code by semantic category (calls, imports, loops, etc.)

GitDiffFileLine-level unified diff between revisions

SQL Macros

Available via the query tool (analyst profile). Composable with joins, filters, and aggregations.

Files

`list_files(pattern)`	Find files by glob pattern
`read_source(path, lines, ctx, match)`	Read file with line ranges and filtering
`read_source_batch(pattern, lines, ctx)`	Read multiple files by glob
`read_context(path, center_line, ctx)`	Read lines around a target line
`file_line_count(pattern)`	Line counts per file
`project_overview(root)`	File counts by language
`read_as_table(path, lim)`	Preview CSV/JSON as a table

Code

`find_definitions(pattern, name)`	AST search for functions, classes, variables
`find_in_ast(pattern, kind, name)`	Semantic AST search by category (calls, imports, loops, conditionals, strings, comments)
`find_calls(pattern, name)`	Find function call sites
`find_imports(pattern)`	Find import statements
`code_structure(pattern)`	Top-level definitions per file
`complexity_hotspots(pattern, n)`	Functions ranked by cyclomatic complexity
`function_callers(pattern, name)`	Who calls a given function
`module_dependencies(pattern, pkg)`	Internal import graph with fan-in

Docs

`doc_outline(pattern, max_lvl)`	Markdown table of contents
`read_doc_section(path, id)`	Read a markdown section by ID
`find_code_examples(pattern, lang)`	Extract fenced code blocks
`doc_stats(pattern)`	Word/section/code-block counts

Git

`recent_changes(n, repo)`	Commit history
`branch_list(repo)`	List branches
`tag_list(repo)`	List tags
`repo_files(rev, repo)`	Files in a git tree
`file_at_version(file, rev, repo)`	File content at a revision
`file_changes(from, to, repo)`	Files changed between revisions
`file_diff(file, from, to, repo)`	Line-level unified diff
`working_tree_status(repo)`	Untracked/deleted files
`structural_diff(file, from, to)`	Semantic diff: added/removed/modified definitions
`changed_function_summary(from, to, pattern)`	Changed functions ranked by complexity

Conversations

`sessions()`	One row per Claude Code session
`messages()`	Flattened user + assistant messages
`content_blocks()`	Unnested assistant content blocks
`tool_calls()`	Extracted tool_use blocks
`tool_results()`	Matched tool_result blocks
`token_usage()`	Per-message token consumption
`tool_frequency()`	Tool usage counts
`bash_commands()`	Parsed bash commands with categories
`session_summary()`	Dashboard view with all stats
`model_usage()`	Token consumption by model
`search_messages(term)`	Full-text search across content
`search_tool_inputs(term)`	Search within tool parameters

SQL macros, not bash

-- Instead of: grep -rn "def parse" src/ SELECT * FROM find_definitions('src/**/*.py', '%parse%'); -- Cross-tier: definitions in recently changed files SELECT * FROM changed_function_summary('HEAD~5', 'HEAD', '**/*.py');

CLI for humans

Enable the CLI tool option above to also install a terminal interface. Same macros, same data — no MCP required.

# List commands and their arguments $ fledgling help # Search for function definitions $ fledgling find-definitions 'src/**/*.py' '%parse%' # Recent git history, specific columns $ fledgling recent-changes 10 -c hash,message # Named parameters $ fledgling list-files '**/*.py' --commit=HEAD~1 # Output as CSV or JSON $ fledgling code-structure 'lib/**/*.rs' -f csv # Raw SQL passthrough $ fledgling query "SELECT * FROM sessions() LIMIT 5"

After installing, move the CLI to your PATH:

chmod +x .fledgling-cli && mv .fledgling-cli ~/.local/bin/fledgling

Fledgling Pro

A FastMCP server that adds coordination intelligence on top of the SQL macros.

pip install fledgling-mcp[pro]

Smart DefaultsAuto-detects language, doc dir, git branch

Token AwarenessAuto-truncation with hints and bypass

Compound Workflowsexplore, investigate, review, search in one call

Session StateCaching, access log, kibitzer suggestions

MCP ResourcesProject context always available

Prompt TemplatesContext-aware exploration and review workflows

Python API

import fledgling con = fledgling.connect() con.find_definitions('**/*.py', name_pattern='parse%').show() con.recent_changes(5).select('hash, message').df() con.code_structure('src/**/*.py').filter('cyclomatic_complexity > 5').show()

Coming Soon: fledgling-edit

AST-aware code editing — rename, remove, move, and pattern-rewrite using structural targets instead of line numbers. Design docs (experimental).