Fledgling Skill Guide

Fledgling gives you structured, token-efficient access to the codebase you're working in. Instead of reading raw files and guessing at structure, you get targeted tools backed by SQL macros and real parsers (AST for code, markdown parser for docs, git for history).

Quick Reference

Tools

Tool	Purpose	Key params
ReadLines	Read file content with line ranges, context, and match filtering	file_path, lines, match, commit
FindDefinitions	AST-based search for functions, classes, variables	file_pattern, name_pattern
FindCode	CSS selector search: .func, #name, :has(...), ::callers	file_pattern, selector
ViewCode	View source matched by CSS selector with context lines	file_pattern, selector, context
SelectCode	Render selector matches as markdown: file:range headings + full source blocks	source, selector
CodeStructure	Top-level overview: what's defined in each file	file_pattern
ExploreProject	First-contact briefing: languages, structure, docs, recent activity	root, code_pattern, doc_pattern
InvestigateSymbol	Deep dive: definitions, callers, call sites for a symbol	name, file_pattern
ReviewChanges	Change review: files and functions ranked by complexity	from_rev, to_rev, file_pattern
SearchProject	Multi-source search across definitions, calls, and docs	pattern, file_pattern
MDOverview	Browse all docs with keyword/regex search	file_pattern, search
MDSection	Read a markdown section by ID	file_path, section_id
GitDiffSummary	File-level change summary between revisions	from_rev, to_rev
GitShow	File content at a specific git revision	file, rev
Help	This guide (no args = outline, section_id = details)	section
ChatSessions	Browse conversation sessions	project, days, limit
ChatSearch	Search across conversation messages	query, role
ChatToolUsage	Tool usage frequency	project, days
ChatDetail	Deep view of a single session	session_id
SearchContent	BM25 full-text search over docs + code (requires rebuild first)	query, kind, extractor, limit
SearchDocs	BM25 search over markdown sections	query, limit
SearchCode	BM25 search over code (definition/comment/string)	query, kind, limit
FtsStats	Diagnostic: counts per extractor/kind in the FTS index	—

Query-Only Macros

These macros are available via the query tool. They provide the full power of Fledgling's SQL composability — you can join, filter, and aggregate across them.

Macro	Purpose	Example
list_files(pattern)	Find files by glob	SELECT * FROM list_files('src/**/*.py')
project_overview(root)	File counts by language	SELECT * FROM project_overview('.')
read_as_table(path, limit)	Preview CSV/JSON/Parquet as table	SELECT * FROM read_as_table('data.csv')
find_calls(pattern, name)	Find function call sites	SELECT * FROM find_calls('src/**/*.py', 'connect')
find_imports(pattern)	Find import statements	SELECT * FROM find_imports('src/**/*.py')
complexity_hotspots(pattern, n)	Functions ranked by cyclomatic complexity	SELECT * FROM complexity_hotspots('src/**/*.py', 10)
function_callers(pattern, name)	Who calls a function?	SELECT * FROM function_callers('src/**/*.py', 'validate')
module_dependencies(pattern, pkg)	Internal import graph with fan-in	SELECT * FROM module_dependencies('src/**/*.py', 'myapp')
doc_outline(pattern, max_level)	Markdown table of contents	SELECT * FROM doc_outline('docs/**/*.md')
recent_changes(n, repo)	Commit history	SELECT * FROM recent_changes(10)
branch_list(repo)	List branches	SELECT * FROM branch_list()
tag_list(repo)	List tags	SELECT * FROM tag_list()
file_changes(from, to, repo)	Files changed between revisions	SELECT * FROM file_changes('HEAD~3', 'HEAD')
file_diff(file, from, to, repo)	Line-level unified diff	SELECT * FROM file_diff('src/main.py', 'HEAD~1', 'HEAD')
working_tree_status(repo)	Untracked/deleted files	SELECT * FROM working_tree_status()
structural_diff(file, from, to)	Semantic diff: added/removed/modified definitions	SELECT * FROM structural_diff('src/main.py', 'HEAD~1', 'HEAD')
changed_function_summary(from, to, pattern)	Functions in changed files, ranked by cyclomatic complexity	SELECT * FROM changed_function_summary('HEAD~5', 'HEAD', 'src/**/*.py')

Tools

ReadLines

Read file content with precision. Replaces cat/head/tail with structured output.

Returns: line_number, content

ReadLines(file_path="src/main.py")                    # whole file
ReadLines(file_path="src/main.py", lines="10-25")     # line range
ReadLines(file_path="src/main.py", lines="42", ctx="5")  # line 42 +/- 5 lines
ReadLines(file_path="src/main.py", match="import")    # only matching lines
ReadLines(file_path="src/main.py", lines="1-50", match="def")  # combined
ReadLines(file_path="src/main.py", commit="HEAD~1")   # previous version

FindDefinitions

Find where things are defined: functions, classes, methods, variables. AST-based, not text matching.

Returns: file_path, name, kind, start_line, end_line, signature

FindDefinitions(file_pattern="src/**/*.py")                # all definitions
FindDefinitions(file_pattern="src/**/*.py", name_pattern="parse%")  # names starting with "parse"
FindDefinitions(file_pattern="lib/*.ts", name_pattern="%Handler")   # names ending with "Handler"

The name_pattern uses SQL LIKE wildcards: % matches any sequence, _ matches one character.

CodeStructure

High-level overview of what's defined in files, with line counts. Good first step to understand unfamiliar code.

Returns: file_path, name, kind, start_line, end_line, line_count

CodeStructure(file_pattern="src/**/*.py")
CodeStructure(file_pattern="lib/auth.ts")

MDSection

Read a specific markdown section by ID. Use doc_outline() via the query tool to discover section IDs first.

Returns: section_id, title, level, content, start_line, end_line

MDSection(file_path="docs/guide.md", section_id="installation")
MDSection(file_path="README.md", section_id="getting-started")

GitDiffSummary

File-level summary of changes between two git revisions. For function-level analysis, use structural_diff() or changed_function_summary() via the query tool.

Returns: file_path, status, old_size, new_size

GitDiffSummary(from_rev="HEAD~1", to_rev="HEAD")
GitDiffSummary(from_rev="main", to_rev="feature-branch")

GitShow

Show file content at a specific git revision. Replaces git show rev:path.

Returns: file_path, ref, size_bytes, content

GitShow(file="README.md", rev="HEAD~1")
GitShow(file="sql/repo.sql", rev="main")

Help

This guide. Call with no args to see the section outline, or pass a section ID for details.

Help()                              # outline
Help(section="workflows")           # specific section

Code Intelligence

All code tools use AST parsing (via sitting_duck), not text matching. They work across 30 languages including Python, JavaScript, TypeScript, Rust, Go, Java, C/C++, Ruby, and more.

Use ast_supported_languages() via the query tool for the live list.

Composing Macros

The real power of Fledgling is composing macros via the query tool. Examples:

-- Complex functions in recently changed files
SELECT h.file_path, h.name, h.cyclomatic, h.lines
FROM complexity_hotspots('src/**/*.py') h
WHERE h.file_path IN (
    SELECT file_path FROM changed_function_summary('main', 'HEAD', 'src/**/*.py')
);

-- Module dependency fan-in (what's the most-imported module?)
SELECT target_module, fan_in
FROM module_dependencies('src/**/*.py', 'myapp')
ORDER BY fan_in DESC;

-- Functions over 20 lines with high complexity
SELECT file_path, name, cyclomatic, lines
FROM complexity_hotspots('src/**/*.py', 100)
WHERE cyclomatic > 10 AND lines > 20;

Workflows

Explore an Unfamiliar Codebase

Quick (one call): ExploreProject() — returns languages, top-complexity definitions, doc outline, and recent git activity in one structured result.

Detailed (step-by-step):

1. CodeStructure(file_pattern="src/**/*.py") — see what's defined where
2. ReadLines(file_path="src/main.py") — read key files
3. MDOverview(file_pattern="*.md") — find docs
4. MDSection(file_path="README.md", section_id="...") — read relevant docs

Understand a Function

Quick (one call): InvestigateSymbol(name="my_func") — returns definitions, callers, and call sites in one result.

Detailed (step-by-step):

1. FindDefinitions(file_pattern="src/**/*.py", name_pattern="my_func%") — find it
2. ReadLines(file_path="src/module.py", lines="42-80") — read implementation
3. Use query tool: SELECT * FROM function_callers('src/**/*.py', 'my_func') — who calls it?

Review Recent Changes

Quick (one call): ReviewChanges(from_rev="HEAD~3", to_rev="HEAD") — returns changed files and functions ranked by complexity.

Detailed (step-by-step):

1. GitDiffSummary(from_rev="HEAD~3", to_rev="HEAD") — which files changed
2. Use query tool: SELECT * FROM changed_function_summary('HEAD~3', 'HEAD', 'src/**/*.py') — what functions are affected
3. Use query tool: SELECT * FROM complexity_hotspots('src/**/*.py', 10) — what's risky
4. ReadLines(file_path="src/changed.py", lines="42-80") — read the changes

Search Across Sources

Quick (one call): SearchProject(pattern="parse%") — searches definitions, call sites, and docs simultaneously.

View Code by Selector

Use CSS selectors to find and view code structurally:

FindCode(file_pattern="src/**/*.py", selector=".func#validate")
ViewCode(file_pattern="src/**/*.py", selector=".func:has(.call#execute)")
SelectCode(source="src/**/*.py", selector=".class > .func")

Selector syntax: .func, .class, .call, .import, #name, :has(child), :not(...), ::callers, ::callees, A > B (direct child), A ~ B (sibling).

Analyze Architecture

1. Use query tool: SELECT * FROM module_dependencies('src/**/*.py', 'myapp') — import graph
2. CodeStructure(file_pattern="src/core/*.py") — core module structure
3. Use query tool: SELECT * FROM complexity_hotspots('src/**/*.py', 20) — complexity hotspots

Macro Reference

All macros are available via the query tool.

Files

Macro	Signature
list_files	(pattern, commit := NULL)
read_source	(file_path, lines := NULL, ctx := 0, match := NULL)
read_source_batch	(file_pattern, lines := NULL, ctx := 0)
read_context	(file_path, center_line, ctx := 5)
file_line_count	(file_pattern)
project_overview	(root := '.')
read_as_table	(file_path, lim := 100)

Code

Macro	Signature
find_definitions	(file_pattern, name_pattern := '%')
find_calls	(file_pattern, name_pattern := '%')
find_imports	(file_pattern)
find_code	(file_pattern, selector, lang := NULL)
find_code_grep	(file_pattern, selector, lang := NULL)
view_code	(file_pattern, selector, lang := NULL, ctx := 0)
view_code_text	(file_pattern, selector, lang := NULL, ctx := 0)
code_structure	(file_pattern)
find_class_members	(file_path, class_node_id)
complexity_hotspots	(file_pattern, n := 20)
function_callers	(file_pattern, func_name)
module_dependencies	(file_pattern, package_prefix)

Structural Analysis

Macro	Signature
structural_diff	(file, from_rev, to_rev, repo := '.')
changed_function_summary	(from_rev, to_rev, file_pattern, repo := '.')

Workflows

Macro	Signature
explore_query	(root := '.', code_pattern := '**/*.py', doc_pattern := 'docs/**/*.md', top_n := 20, recent_n := 10)
investigate_query	(name, file_pattern := '**/*.py')
review_query	(from_rev := 'HEAD~1', to_rev := 'HEAD', file_pattern := '**/*.py', repo := '.', top_n := 20)
search_query	(pattern, file_pattern := '**/*.py', doc_pattern := 'docs/**/*.md', top_n := 50)
pss_render	(source, selector)
ast_select_render	(source, selector)

Docs

Macro	Signature
doc_outline	(file_pattern, max_lvl := 3)
read_doc_section	(file_path, target_id)
find_code_examples	(file_pattern, lang := NULL)
doc_stats	(file_pattern)

Git

Macro	Signature
recent_changes	(n := 10, repo := '.')
branch_list	(repo := '.')
tag_list	(repo := '.')
repo_files	(rev := 'HEAD', repo := '.')
file_at_version	(file, rev, repo := '.')
file_changes	(from_rev, to_rev, repo := '.')
file_diff	(file, from_rev, to_rev, repo := '.')
working_tree_status	(repo := '.')

Conversations

Macro	Signature
sessions	()
messages	()
content_blocks	()
tool_calls	()
tool_results	()
token_usage	()
tool_frequency	()
bash_commands	()
session_summary	()
model_usage	()
search_messages	(search_term)
search_tool_inputs	(search_term)

Help

Macro	Signature
help	(target_id := NULL)

Tips

Supported Languages

Use ast_supported_languages() via the query tool to check the live list of languages supported by the code intelligence tools.

Glob Patterns

• * matches within a directory: src/*.py
• ** matches across directories: src/**/*.py
• Combine extensions: src/**/*.{py,ts}

Path Handling

• Paths are resolved relative to the project root
• Use absolute paths when outside the project
• Git mode paths are always repo-relative
• The sandbox restricts filesystem access to the project directory; use dedicated tools instead of raw SQL for file operations

Discovering Macro Schemas

Use the describe tool to inspect what columns a macro returns:

describe(query="SELECT * FROM complexity_hotspots('test', 1)")

This reveals column names and types, making it easier to compose macros via joins.

Data File Formats

read_as_table(path) auto-detects format by extension:

Extension	Reader	Built-in?
.csv, .tsv	read_csv_auto	Yes
.json, .jsonl	read_json_auto	Yes
.parquet, .pq	read_parquet	Yes

Unsupported extensions fall back to CSV. For other formats, use the query tool with DuckDB's native readers directly (e.g., SELECT * FROM 'data.xlsx' if the spatial extension is installed).

Token Efficiency

• Use CodeStructure first to understand what's in a file before reading it
• Use FindDefinitions with name_pattern to narrow results
• Use FindCode with CSS selectors for targeted structural searches (.call#execute, .import, :has(...))
• Use ReadLines with lines and match to read only what you need
• Use doc_outline() via query before MDSection to find the right section