squackit 0.3.2__tar.gz → 0.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. {squackit-0.3.2 → squackit-0.4.0}/.gitignore +2 -0
  2. {squackit-0.3.2 → squackit-0.4.0}/PKG-INFO +2 -2
  3. {squackit-0.3.2 → squackit-0.4.0}/docs/architecture.md +42 -12
  4. {squackit-0.3.2 → squackit-0.4.0}/docs/configuration.md +7 -7
  5. {squackit-0.3.2 → squackit-0.4.0}/docs/index.md +24 -7
  6. squackit-0.4.0/docs/quickstart.md +172 -0
  7. {squackit-0.3.2 → squackit-0.4.0}/docs/tools.md +89 -62
  8. {squackit-0.3.2 → squackit-0.4.0}/pyproject.toml +2 -2
  9. {squackit-0.3.2 → squackit-0.4.0}/squackit/__init__.py +1 -1
  10. {squackit-0.3.2 → squackit-0.4.0}/squackit/cli.py +35 -5
  11. {squackit-0.3.2 → squackit-0.4.0}/squackit/server.py +9 -3
  12. squackit-0.4.0/squackit/tools.py +207 -0
  13. {squackit-0.3.2 → squackit-0.4.0}/tests/test_cli_tools.py +17 -0
  14. {squackit-0.3.2 → squackit-0.4.0}/tests/test_smoke.py +1 -1
  15. squackit-0.4.0/tests/test_tools.py +282 -0
  16. squackit-0.3.2/docs/quickstart.md +0 -104
  17. squackit-0.3.2/squackit/tools.py +0 -102
  18. squackit-0.3.2/tests/test_tools.py +0 -92
  19. {squackit-0.3.2 → squackit-0.4.0}/.github/workflows/release.yml +0 -0
  20. {squackit-0.3.2 → squackit-0.4.0}/.mcp.json +0 -0
  21. {squackit-0.3.2 → squackit-0.4.0}/.readthedocs.yaml +0 -0
  22. {squackit-0.3.2 → squackit-0.4.0}/.readthedocs.yml +0 -0
  23. {squackit-0.3.2 → squackit-0.4.0}/CLAUDE.md +0 -0
  24. {squackit-0.3.2 → squackit-0.4.0}/LICENSE +0 -0
  25. {squackit-0.3.2 → squackit-0.4.0}/README.md +0 -0
  26. {squackit-0.3.2 → squackit-0.4.0}/docs/prompts.md +0 -0
  27. {squackit-0.3.2 → squackit-0.4.0}/docs/resources.md +0 -0
  28. {squackit-0.3.2 → squackit-0.4.0}/docs/superpowers/plans/2026-04-10-phase1-handoff.md +0 -0
  29. {squackit-0.3.2 → squackit-0.4.0}/docs/superpowers/plans/2026-04-10-squawkit-extraction.md +0 -0
  30. {squackit-0.3.2 → squackit-0.4.0}/docs/superpowers/plans/2026-04-11-phase3-pluckit-rewire.md +0 -0
  31. {squackit-0.3.2 → squackit-0.4.0}/docs/superpowers/plans/2026-04-12-cli-tool-exposure.md +0 -0
  32. {squackit-0.3.2 → squackit-0.4.0}/docs/superpowers/plans/2026-04-12-pluckit-tool-integration.md +0 -0
  33. {squackit-0.3.2 → squackit-0.4.0}/docs/superpowers/plans/2026-04-12-session-handoff.md +0 -0
  34. {squackit-0.3.2 → squackit-0.4.0}/docs/superpowers/specs/2026-04-10-squawkit-design.md +0 -0
  35. {squackit-0.3.2 → squackit-0.4.0}/docs/superpowers/specs/2026-04-12-cli-tool-exposure-design.md +0 -0
  36. {squackit-0.3.2 → squackit-0.4.0}/docs/superpowers/specs/2026-04-12-pluckit-tool-integration-design.md +0 -0
  37. {squackit-0.3.2 → squackit-0.4.0}/mkdocs.yml +0 -0
  38. {squackit-0.3.2 → squackit-0.4.0}/squackit/__main__.py +0 -0
  39. {squackit-0.3.2 → squackit-0.4.0}/squackit/db.py +0 -0
  40. {squackit-0.3.2 → squackit-0.4.0}/squackit/defaults.py +0 -0
  41. {squackit-0.3.2 → squackit-0.4.0}/squackit/formatting.py +0 -0
  42. {squackit-0.3.2 → squackit-0.4.0}/squackit/prompts.py +0 -0
  43. {squackit-0.3.2 → squackit-0.4.0}/squackit/session.py +0 -0
  44. {squackit-0.3.2 → squackit-0.4.0}/squackit/tool_config.py +0 -0
  45. {squackit-0.3.2 → squackit-0.4.0}/squackit/workflows.py +0 -0
  46. {squackit-0.3.2 → squackit-0.4.0}/tests/conftest.py +0 -0
  47. {squackit-0.3.2 → squackit-0.4.0}/tests/test_defaults.py +0 -0
  48. {squackit-0.3.2 → squackit-0.4.0}/tests/test_formatting_json.py +0 -0
  49. {squackit-0.3.2 → squackit-0.4.0}/tests/test_prompts.py +0 -0
  50. {squackit-0.3.2 → squackit-0.4.0}/tests/test_resources.py +0 -0
  51. {squackit-0.3.2 → squackit-0.4.0}/tests/test_session.py +0 -0
  52. {squackit-0.3.2 → squackit-0.4.0}/tests/test_tool_config.py +0 -0
  53. {squackit-0.3.2 → squackit-0.4.0}/tests/test_truncation.py +0 -0
  54. {squackit-0.3.2 → squackit-0.4.0}/tests/test_workflows.py +0 -0
@@ -6,6 +6,8 @@ __pycache__/
6
6
  venv/
7
7
  dist/
8
8
  build/
9
+ site/
9
10
  *.egg-info/
10
11
  .DS_Store
12
+ .squackit/
11
13
  .squawkit/
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: squackit
3
- Version: 0.3.2
3
+ Version: 0.4.0
4
4
  Summary: Semi-QUalified Agent Companion Kit — the stateful intelligence + MCP server layer for fledgling-equipped agents.
5
5
  Project-URL: Homepage, https://github.com/teaguesterling/squackit
6
6
  Project-URL: Documentation, https://squackit.readthedocs.io
@@ -16,7 +16,7 @@ Classifier: License :: OSI Approved :: Apache Software License
16
16
  Classifier: Programming Language :: Python :: 3
17
17
  Classifier: Topic :: Software Development :: Libraries :: Python Modules
18
18
  Requires-Python: >=3.9
19
- Requires-Dist: ast-pluckit>=0.7.0
19
+ Requires-Dist: ast-pluckit>=0.9.0
20
20
  Requires-Dist: click>=8.0
21
21
  Requires-Dist: fastmcp>=3.0
22
22
  Provides-Extra: docs
@@ -19,8 +19,8 @@ Layer 2 fledgling-python ── thin Python bundler
19
19
  │ connect(), attach(), configure()
20
20
 
21
21
  Layer 1 fledgling ──── SQL macros (language-agnostic)
22
- find_definitions, code_structure,
23
- doc_outline, recent_changes, ...
22
+ read_source, doc_outline,
23
+ recent_changes, file_diff, ...
24
24
 
25
25
  Layer 0 DuckDB extensions
26
26
  sitting_duck (AST parsing)
@@ -36,9 +36,9 @@ These are enforced at the package level, not just by convention:
36
36
  1. **squackit imports pluckit, never fledgling-python.** If squackit needs
37
37
  a capability pluckit doesn't expose, pluckit grows the capability.
38
38
 
39
- 2. **squackit never constructs SQL strings.** It calls tools via the
40
- fledgling Connection proxy that pluckit provides, which auto-generates
41
- Python wrappers for every published SQL macro.
39
+ 2. **squackit never constructs SQL strings directly.** It calls tools via
40
+ the fledgling Connection proxy (for fledgling macros) or pluckit's
41
+ fluent API (for pluckit tools).
42
42
 
43
43
  3. **squackit is the only layer with session state.** Pluckit holds no
44
44
  per-call memory. Fledgling-python holds no per-call memory.
@@ -46,37 +46,45 @@ These are enforced at the package level, not just by convention:
46
46
  4. **squackit is the only layer that knows about MCP.** FastMCP wiring,
47
47
  prompt templates, and resource handlers live exclusively in squackit.
48
48
 
49
+ 5. **Pluckit tools take priority over fledgling equivalents.** When both
50
+ provide a capability, pluckit wins (via the `extra_tools` parameter
51
+ and `MASKED_BY_PLUCKIT` set in `tool_config.py`).
52
+
49
53
  ## Module responsibilities
50
54
 
51
55
  | Module | Role |
52
56
  |--------|------|
53
- | `server.py` | FastMCP server wiring. Auto-registers fledgling macros as MCP tools, defines resources, connects prompts and workflows. The main entry point. |
57
+ | `cli.py` | Click-based CLI. `squackit mcp serve`, `squackit tool <name>`, `squackit pluck`. Dynamic command generation from the tool registry. |
58
+ | `server.py` | FastMCP server wiring. Registers fledgling macros and pluckit tools as MCP tools, defines resources, connects prompts and workflows. |
59
+ | `tool_config.py` | `ToolPresentation` dataclass wrapping fledgling `ToolInfo`. `build_tool_registry()` unifies fledgling macros and pluckit tools with priority-based masking. |
60
+ | `tools.py` | Pluckit-backed tool executors (`view`, `find`, `find_names`, `complexity`) and their `ToolPresentation` definitions. |
54
61
  | `defaults.py` | Project inference. Analyzes the codebase at startup to determine `code_pattern`, `doc_pattern`, `main_branch`. Reads config file overrides. |
55
- | `formatting.py` | Token-aware truncation. Head+tail display, omission messages, bypass logic for narrowing parameters. |
62
+ | `formatting.py` | Token-aware truncation. Head+tail display, omission messages, bypass logic for narrowing parameters. JSON output formatter. |
56
63
  | `workflows.py` | Compound workflow tools. `explore`, `investigate`, `review`, `search` — each composes multiple fledgling macros into a single briefing. |
57
64
  | `session.py` | Session state. `SessionCache` (in-memory with TTL) and `AccessLog` (records every tool call). |
58
65
  | `prompts.py` | MCP prompt templates. `explore`, `investigate`, `review` — pre-load live data into structured workflow instructions. |
59
- | `db.py` | Connection factory. Thin wrapper over `pluckit.Plucker(...).connection` that returns a fledgling-enabled Connection proxy. |
66
+ | `db.py` | Connection factory. Thin wrapper over `pluckit.Plucker(...).connection`. |
60
67
 
61
68
  ## How a tool call flows
62
69
 
70
+ **Fledgling macro tool (e.g., `read_source`):**
71
+
63
72
  ```
64
- Agent calls "find_definitions" via MCP
73
+ Agent calls "read_source" via MCP
65
74
 
66
75
 
67
76
  server.py: _register_tool handler
68
77
 
69
78
  ├─ Apply smart defaults (defaults.py)
70
- │ file_pattern = agent's value or inferred code_pattern
71
79
 
72
80
  ├─ Check session cache (session.py)
73
81
  │ Cache hit → return cached result with "(cached)" note
74
82
 
75
83
  ├─ Execute macro via Connection proxy
76
- │ con.find_definitions(file_pattern=..., name_pattern=...)
84
+ │ con.read_source(file_path=..., lines=...)
77
85
  │ │
78
86
  │ ▼
79
- pluckit → fledgling-python → DuckDB → sitting_duck
87
+ │ fledgling-python → DuckDB → sitting_duck
80
88
 
81
89
  ├─ Format result (formatting.py)
82
90
  │ Truncate if over limit, add head+tail hints
@@ -86,6 +94,28 @@ server.py: _register_tool handler
86
94
  └─ Return formatted text to agent
87
95
  ```
88
96
 
97
+ **Pluckit tool (e.g., `view`):**
98
+
99
+ ```
100
+ Agent calls "view" via MCP
101
+
102
+
103
+ server.py: _register_executor_tool handler
104
+
105
+ ├─ Call ToolPresentation.executor(source=..., selector=...)
106
+ │ │
107
+ │ ▼
108
+ │ squackit/tools.py: view_executor
109
+ │ │
110
+ │ ▼
111
+ │ Plucker(code=source, plugins=[AstViewer]).view(selector)
112
+
113
+ ├─ Type-dispatch formatting
114
+ │ View → markdown | DuckDBPyRelation → table | list → lines
115
+
116
+ └─ Return formatted text to agent
117
+ ```
118
+
89
119
  ## What squackit is NOT
90
120
 
91
121
  - **Not a code editor.** squackit reads and analyzes code; it doesn't
@@ -11,7 +11,8 @@ squackit infers project settings at startup by analyzing the codebase:
11
11
  | `main_branch` | Git HEAD reference | `main` |
12
12
 
13
13
  These defaults are used whenever a tool parameter is omitted. For example,
14
- `find_definitions()` with no `file_pattern` uses the inferred `code_pattern`.
14
+ a tool that takes `file_pattern` will use the inferred `code_pattern` when
15
+ none is passed.
15
16
 
16
17
  ## Config file
17
18
 
@@ -52,8 +53,7 @@ Cache policies vary by tool:
52
53
 
53
54
  | Tool category | TTL | Invalidation |
54
55
  |---------------|-----|-------------|
55
- | `project_overview`, `explore` | Session lifetime | Never (run once) |
56
- | `find_definitions`, `code_structure` | 5 minutes | Time-based |
56
+ | `project_overview`, `doc_outline` | Session lifetime | Never |
57
57
  | `read_source`, `read_context` | 5 minutes | File mtime change |
58
58
  | `doc_outline` | Session lifetime | Never |
59
59
  | `recent_changes` | 30 seconds | Time-based |
@@ -69,7 +69,7 @@ Every tool has configurable output limits:
69
69
  | Tool type | Default limit | Parameter |
70
70
  |-----------|---------------|-----------|
71
71
  | Content tools (`read_source`, `file_diff`) | 200 lines | `max_lines` |
72
- | Discovery tools (`find_definitions`, `list_files`) | 50 rows | `max_results` |
72
+ | Discovery tools (`list_files`, `doc_outline`) | 50-100 rows | `max_results` |
73
73
  | Git tools (`file_changes`, `recent_changes`) | 20-25 rows | `max_results` |
74
74
 
75
75
  Truncated output shows head + tail with a hint:
@@ -85,8 +85,8 @@ Use lines='N-M' to see a range, or match='keyword' to filter.
85
85
  ```
86
86
 
87
87
  **Automatic bypass:** providing a narrowing parameter (`lines`, `match`,
88
- `name_pattern`) disables truncation. The agent is already being specific,
89
- so the cap gets out of the way.
88
+ `search`) disables truncation. The agent is already being specific, so the
89
+ cap gets out of the way.
90
90
 
91
91
  ## Environment variables
92
92
 
@@ -102,7 +102,7 @@ When using squackit programmatically:
102
102
  from squackit.server import create_server
103
103
 
104
104
  mcp = create_server(
105
- name="fledgling", # MCP server name
105
+ name="squackit", # MCP server name
106
106
  root="/path/to/project", # Project root (default: cwd)
107
107
  init=None, # Init file: None=auto, False=skip, path=explicit
108
108
  modules=None, # SQL modules to load (default: all for profile)
@@ -12,15 +12,24 @@ in fledgling's neutral SQL core.
12
12
 
13
13
  ## What it does
14
14
 
15
- When an AI agent connects to squackit's MCP server, it gets:
15
+ squackit wears two hats: an MCP server for AI agents, and a CLI for humans.
16
16
 
17
- - **25+ tools** for reading code, searching definitions, browsing docs, inspecting git history, and running diagnostics — all powered by fledgling's DuckDB macros
17
+ **For agents via MCP:**
18
+
19
+ - **20+ tools** for reading code, searching definitions (CSS selectors via pluckit), browsing docs, inspecting git history, and running diagnostics
18
20
  - **4 compound workflows** (`explore`, `investigate`, `review`, `search`) that compose multiple tools into single-call briefings
19
21
  - **3 prompt templates** that pre-load live project data into exploration, debugging, and review workflows
20
22
  - **5 always-on resources** exposing project overview, diagnostics, docs, git status, and session history
21
- - **Smart defaults** that infer your project's language, doc layout, and main branch so tools work without configuration
22
- - **Token-aware output** with configurable truncation, head+tail display, and automatic bypass when the agent narrows its query
23
- - **Session caching** with per-tool TTL policies and mtime-based invalidation for content tools
23
+ - **Smart defaults** that infer your project's language, doc layout, and main branch
24
+ - **Token-aware output** with configurable truncation and automatic bypass when the agent narrows its query
25
+ - **Session caching** with per-tool TTL policies and mtime-based invalidation
26
+
27
+ **For humans via CLI:**
28
+
29
+ - **`squackit tool <name>`** — run any tool from the shell with structured (`--json`) or human-readable output
30
+ - **`squackit pluck ...`** — direct access to pluckit chain queries
31
+ - **`squackit mcp serve`** — start the MCP server
32
+ - Tool names resolve in three conventions (underscore, kebab-case, CamelCase) with shell tab completion
24
33
 
25
34
  ## Quick install
26
35
 
@@ -28,10 +37,18 @@ When an AI agent connects to squackit's MCP server, it gets:
28
37
  pip install squackit
29
38
  ```
30
39
 
31
- Then start the MCP server:
40
+ Then use the CLI:
41
+
42
+ ```bash
43
+ squackit tool list
44
+ squackit tool view "src/**/*.py" ".fn#main"
45
+ squackit tool project_overview
46
+ ```
47
+
48
+ Or start the MCP server:
32
49
 
33
50
  ```bash
34
- squackit
51
+ squackit mcp serve
35
52
  ```
36
53
 
37
54
  Or use it programmatically:
@@ -0,0 +1,172 @@
1
+ # Getting Started
2
+
3
+ ## Installation
4
+
5
+ ### From PyPI
6
+
7
+ ```bash
8
+ pip install squackit
9
+ ```
10
+
11
+ This installs squackit and its dependencies ([ast-pluckit](https://pypi.org/project/ast-pluckit/),
12
+ fastmcp, and transitively fledgling-mcp and duckdb).
13
+
14
+ ### From source (development)
15
+
16
+ ```bash
17
+ git clone https://github.com/teaguesterling/squackit.git
18
+ cd squackit
19
+ pip install -e ".[docs,test]"
20
+ ```
21
+
22
+ ## Command-line usage
23
+
24
+ squackit ships with a `squackit` CLI that exposes three things:
25
+
26
+ - **`squackit mcp serve`** — start the MCP server (for AI agents)
27
+ - **`squackit tool <name>`** — run any squackit tool from the shell
28
+ - **`squackit pluck ...`** — run pluckit chain queries
29
+
30
+ ### Tool commands
31
+
32
+ ```bash
33
+ squackit tool list # show available tools
34
+ squackit tool view "**/*.py" ".fn#main" # rendered source
35
+ squackit tool find "src/**/*.py" ".class" # AST node metadata
36
+ squackit tool find_names "**/*.py" ".fn" # just the names
37
+ squackit tool complexity "**/*.py" ".fn" # nodes by complexity
38
+ squackit tool read_source squackit/cli.py --lines "1-20"
39
+ squackit tool project_overview
40
+ ```
41
+
42
+ Tool names resolve in three conventions — use whichever you prefer:
43
+
44
+ ```bash
45
+ squackit tool find_names # underscore (canonical)
46
+ squackit tool find-names # kebab-case
47
+ squackit tool FindNames # CamelCase
48
+ squackit t find-names ... # 't' is an alias for 'tool'
49
+ ```
50
+
51
+ ### Structured output
52
+
53
+ Add `--json` for machine-readable output:
54
+
55
+ ```bash
56
+ squackit --json tool find "**/*.py" ".fn" | jq '.[] | .name'
57
+ squackit --json tool list
58
+ ```
59
+
60
+ ### Pluckit chains
61
+
62
+ The `pluck` command passes arguments directly to pluckit's chain evaluator.
63
+ It supports the full selector grammar, navigation, and terminals:
64
+
65
+ ```bash
66
+ squackit pluck "**/*.py" find .fn names
67
+ squackit pluck "src/api.py" find .class children .fn count
68
+ squackit pluck --plugin AstViewer "**/*.py" find ".fn#handler" view
69
+ squackit pluck "**/*.py" find .fn names reset find .class names
70
+ ```
71
+
72
+ See the [pluckit documentation](https://github.com/teaguesterling/pluckit)
73
+ for the full chain grammar.
74
+
75
+ ## Running the MCP server
76
+
77
+ squackit is an [MCP](https://modelcontextprotocol.io/) server that communicates
78
+ over stdio. Start it with:
79
+
80
+ ```bash
81
+ squackit mcp serve
82
+ ```
83
+
84
+ Or via Python:
85
+
86
+ ```bash
87
+ python -m squackit mcp serve
88
+ ```
89
+
90
+ Options:
91
+
92
+ ```bash
93
+ squackit mcp serve --transport sse --port 8080 # SSE transport
94
+ squackit mcp serve --root /path/to/project # explicit project root
95
+ squackit mcp serve --profile analyst # security profile
96
+ ```
97
+
98
+ ### Claude Code integration
99
+
100
+ Add squackit to your Claude Code MCP configuration (`.mcp.json`):
101
+
102
+ ```json
103
+ {
104
+ "mcpServers": {
105
+ "squackit": {
106
+ "command": "squackit",
107
+ "args": ["mcp", "serve"]
108
+ }
109
+ }
110
+ }
111
+ ```
112
+
113
+ ### Programmatic usage
114
+
115
+ ```python
116
+ from squackit.server import create_server
117
+
118
+ # Default: uses current directory, analyst profile
119
+ mcp = create_server()
120
+
121
+ # Custom: specific project root and module selection
122
+ mcp = create_server(
123
+ root="/path/to/project",
124
+ profile="analyst",
125
+ modules=["source", "code", "docs", "repo"],
126
+ )
127
+
128
+ mcp.run()
129
+ ```
130
+
131
+ ## Tab completion
132
+
133
+ squackit's CLI uses Click's built-in shell completion. Activate by adding
134
+ this to your shell profile:
135
+
136
+ ```bash
137
+ # Bash
138
+ eval "$(_SQUACKIT_COMPLETE=bash_source squackit)"
139
+
140
+ # Zsh
141
+ eval "$(_SQUACKIT_COMPLETE=zsh_source squackit)"
142
+
143
+ # Fish
144
+ _SQUACKIT_COMPLETE=fish_source squackit | source
145
+ ```
146
+
147
+ Completion covers all three name conventions (underscore, kebab, CamelCase).
148
+
149
+ ## Configuration
150
+
151
+ squackit infers sensible defaults for your project on startup. Override them
152
+ with a config file at `.squackit/config.toml` (or `.fledgling-python/config.toml`)
153
+ in your project root:
154
+
155
+ ```toml
156
+ [defaults]
157
+ code_pattern = "src/**/*.rs"
158
+ doc_pattern = "documentation/**/*.md"
159
+ main_branch = "develop"
160
+ ```
161
+
162
+ See [Configuration](configuration.md) for all options and precedence rules.
163
+
164
+ ## Verifying the setup
165
+
166
+ After installing, check that everything works:
167
+
168
+ ```bash
169
+ squackit tool project_overview
170
+ ```
171
+
172
+ This should print a table of file counts by language for the current directory.
@@ -1,48 +1,91 @@
1
1
  # Tools Reference
2
2
 
3
- squackit registers fledgling's SQL macros as MCP tools automatically. Each tool
4
- accepts the macro's parameters and returns results as formatted text with
5
- token-aware truncation.
3
+ squackit exposes tools through two sources:
6
4
 
7
- ## Code tools
5
+ - **Pluckit tools** — CSS selector queries over ASTs (`view`, `find`, `find_names`, `complexity`)
6
+ - **Fledgling macros** — SQL-backed tools for file I/O, git, docs, and diagnostics
8
7
 
9
- ### find_definitions
8
+ Pluckit tools take priority when both provide a capability — for example,
9
+ pluckit's `find` replaces fledgling's `find_definitions`, `code_structure`,
10
+ and `complexity_hotspots`.
10
11
 
11
- Find function, class, and module definitions by AST analysis. Use
12
- `name_pattern` with SQL LIKE wildcards (`%`).
12
+ Each tool accepts parameters (required as positional args, optional as
13
+ `--flags`) and returns markdown by default or JSON with `--json`.
14
+
15
+ ## Pluckit tools
16
+
17
+ Pluckit tools use [CSS-like selectors](https://github.com/teaguesterling/pluckit)
18
+ over ASTs. Selectors include `.fn` (functions), `.class`, `.call`, `#name`
19
+ (by name), `[attr]` (by attribute), and combinators like `>`, `+`, `~`.
20
+
21
+ ### view
22
+
23
+ View source code matching selectors. Returns rendered markdown with file
24
+ headings and source blocks.
13
25
 
14
26
  | Parameter | Type | Default | Description |
15
27
  |-----------|------|---------|-------------|
16
- | `file_pattern` | string | inferred | Glob pattern for files to search |
17
- | `name_pattern` | string | `%` | SQL LIKE pattern to filter by name |
28
+ | `source` | string | required | Glob pattern for files |
29
+ | `selector` | string | required | CSS selector |
30
+
31
+ ```bash
32
+ squackit tool view "src/**/*.py" ".fn#main"
33
+ squackit tool view "**/*.py" ".class#AuthService .fn"
34
+ ```
18
35
 
19
- ### find_in_ast
36
+ ### find
20
37
 
21
- Search code by semantic category: calls, imports, definitions, loops,
22
- conditionals, strings, comments.
38
+ Find AST nodes matching selectors. Returns a table with file paths, names,
39
+ types, and line ranges.
23
40
 
24
41
  | Parameter | Type | Default | Description |
25
42
  |-----------|------|---------|-------------|
26
- | `file_pattern` | string | inferred | Glob pattern for files to search |
27
- | `kind` | string | required | Semantic category to search |
28
- | `name` | string | `%` | Name pattern to filter |
43
+ | `source` | string | required | Glob pattern for files |
44
+ | `selector` | string | required | CSS selector |
29
45
 
30
- ### code_structure
46
+ ```bash
47
+ squackit tool find "src/**/*.py" ".fn"
48
+ squackit tool find "**/*.py" ".class > .fn"
49
+ ```
31
50
 
32
- Structural overview with complexity metrics. A good first step for unfamiliar code.
51
+ ### find_names
52
+
53
+ Find just the names of AST nodes matching selectors. Lighter than `find`
54
+ when you only want names.
33
55
 
34
56
  | Parameter | Type | Default | Description |
35
57
  |-----------|------|---------|-------------|
36
- | `file_pattern` | string | inferred | Glob pattern for files to analyze |
58
+ | `source` | string | required | Glob pattern for files |
59
+ | `selector` | string | required | CSS selector |
60
+
61
+ ```bash
62
+ squackit tool find_names "src/**/*.py" ".class"
63
+ ```
37
64
 
38
- ### complexity_hotspots
65
+ ### complexity
39
66
 
40
- Most complex functions in the codebase, ranked by cyclomatic complexity.
67
+ Find AST nodes ranked by complexity (descendant count).
41
68
 
42
69
  | Parameter | Type | Default | Description |
43
70
  |-----------|------|---------|-------------|
44
- | `file_pattern` | string | inferred | Glob pattern |
45
- | `n` | integer | 20 | Number of results |
71
+ | `source` | string | required | Glob pattern for files |
72
+ | `selector` | string | required | CSS selector |
73
+
74
+ ```bash
75
+ squackit tool complexity "src/**/*.py" ".fn"
76
+ ```
77
+
78
+ ### Chain queries (squackit pluck)
79
+
80
+ For multi-step queries (navigation, filtering, batch operations), use
81
+ `squackit pluck` which exposes pluckit's full chain grammar:
82
+
83
+ ```bash
84
+ squackit pluck "**/*.py" find .class children .fn count
85
+ squackit pluck "**/*.py" find .fn containing "cache" names
86
+ ```
87
+
88
+ ## File tools
46
89
 
47
90
  ### read_source
48
91
 
@@ -63,7 +106,7 @@ Read lines centered around a specific line number.
63
106
  |-----------|------|---------|-------------|
64
107
  | `file_path` | string | required | Path to the file |
65
108
  | `center_line` | integer | required | Line to center on |
66
- | `context_lines` | integer | 10 | Lines of context above/below |
109
+ | `ctx` | integer | 10 | Lines of context above/below |
67
110
 
68
111
  ### list_files
69
112
 
@@ -71,13 +114,11 @@ Find files by glob pattern.
71
114
 
72
115
  | Parameter | Type | Default | Description |
73
116
  |-----------|------|---------|-------------|
74
- | `file_pattern` | string | inferred | Glob pattern |
117
+ | `pattern` | string | required | Glob pattern |
75
118
 
76
119
  ### project_overview
77
120
 
78
- File counts by language for the project.
79
-
80
- *No parameters.*
121
+ File counts by language for the project. *No parameters.*
81
122
 
82
123
  ## Documentation tools
83
124
 
@@ -97,7 +138,7 @@ Read a specific markdown section by ID.
97
138
  | Parameter | Type | Default | Description |
98
139
  |-----------|------|---------|-------------|
99
140
  | `file_path` | string | required | Markdown file path |
100
- | `section_id` | integer | required | Section ID from doc_outline |
141
+ | `target_id` | integer | required | Section ID from doc_outline |
101
142
 
102
143
  ## Git tools
103
144
 
@@ -108,6 +149,7 @@ Git commit history.
108
149
  | Parameter | Type | Default | Description |
109
150
  |-----------|------|---------|-------------|
110
151
  | `n` | integer | 20 | Number of commits |
152
+ | `repo` | string | cwd | Repo path |
111
153
 
112
154
  ### file_changes
113
155
 
@@ -115,8 +157,9 @@ Files changed between two git revisions.
115
157
 
116
158
  | Parameter | Type | Default | Description |
117
159
  |-----------|------|---------|-------------|
118
- | `from_rev` | string | inferred | Start revision |
119
- | `to_rev` | string | `HEAD` | End revision |
160
+ | `from_rev` | string | required | Start revision |
161
+ | `to_rev` | string | required | End revision |
162
+ | `repo` | string | cwd | Repo path |
120
163
 
121
164
  ### file_diff
122
165
 
@@ -124,7 +167,7 @@ Line-level unified diff between revisions.
124
167
 
125
168
  | Parameter | Type | Default | Description |
126
169
  |-----------|------|---------|-------------|
127
- | `file_path` | string | required | File to diff |
170
+ | `file` | string | required | File to diff |
128
171
  | `from_rev` | string | inferred | Start revision |
129
172
  | `to_rev` | string | `HEAD` | End revision |
130
173
 
@@ -134,8 +177,8 @@ File content at a specific git revision.
134
177
 
135
178
  | Parameter | Type | Default | Description |
136
179
  |-----------|------|---------|-------------|
137
- | `file_path` | string | required | File path |
138
- | `rev` | string | `HEAD` | Git revision |
180
+ | `file` | string | required | File path |
181
+ | `rev` | string | required | Git revision |
139
182
 
140
183
  ### branch_list
141
184
 
@@ -155,9 +198,9 @@ Semantic diff: added/removed/modified definitions between revisions.
155
198
 
156
199
  | Parameter | Type | Default | Description |
157
200
  |-----------|------|---------|-------------|
201
+ | `file` | string | required | File to diff |
158
202
  | `from_rev` | string | inferred | Start revision |
159
203
  | `to_rev` | string | `HEAD` | End revision |
160
- | `file_pattern` | string | inferred | Glob pattern |
161
204
 
162
205
  ### changed_function_summary
163
206
 
@@ -165,35 +208,17 @@ Changed functions ranked by complexity between revisions.
165
208
 
166
209
  | Parameter | Type | Default | Description |
167
210
  |-----------|------|---------|-------------|
168
- | `from_rev` | string | inferred | Start revision |
169
- | `to_rev` | string | `HEAD` | End revision |
170
- | `file_pattern` | string | inferred | Glob pattern |
171
-
172
- ## Conversation tools
211
+ | `from_rev` | string | required | Start revision |
212
+ | `to_rev` | string | required | End revision |
173
213
 
174
- ### sessions
214
+ ## Conversation tools (MCP only)
175
215
 
176
- Claude Code conversation sessions. *No parameters.*
216
+ These are registered on the MCP server but not exposed via CLI.
177
217
 
178
- ### messages
179
-
180
- Flattened conversation messages.
181
-
182
- | Parameter | Type | Default | Description |
183
- |-----------|------|---------|-------------|
184
- | `session_id` | string | none | Filter by session |
185
-
186
- ### tool_calls
187
-
188
- Tool usage from conversations. *No parameters.*
189
-
190
- ### search_messages
191
-
192
- Full-text search across conversation content.
193
-
194
- | Parameter | Type | Default | Description |
195
- |-----------|------|---------|-------------|
196
- | `query` | string | required | Search text |
218
+ - `sessions` — Claude Code conversation sessions
219
+ - `messages` — Flattened conversation messages
220
+ - `tool_calls` — Tool usage from conversations
221
+ - `search_messages` — Full-text search across conversation content
197
222
 
198
223
  ## Diagnostics
199
224
 
@@ -205,9 +230,11 @@ Fledgling skill guide. No args for outline, section ID for details.
205
230
 
206
231
  Runtime diagnostics: version, profile, modules, extensions.
207
232
 
208
- ## Compound workflow tools
233
+ ## Compound workflow tools (MCP only)
209
234
 
210
- These compose multiple tools into a single-call briefing.
235
+ These compose multiple tools into a single-call briefing. Exposed through
236
+ the MCP server; use the CLI tools individually if you want to run them
237
+ one at a time.
211
238
 
212
239
  ### explore
213
240
 
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "squackit"
3
- version = "0.3.2"
3
+ version = "0.4.0"
4
4
  description = "Semi-QUalified Agent Companion Kit — the stateful intelligence + MCP server layer for fledgling-equipped agents."
5
5
  readme = "README.md"
6
6
  license = "Apache-2.0"
@@ -17,7 +17,7 @@ classifiers = [
17
17
  "License :: OSI Approved :: Apache Software License",
18
18
  ]
19
19
  dependencies = [
20
- "ast-pluckit>=0.7.0",
20
+ "ast-pluckit>=0.9.0",
21
21
  "click>=8.0",
22
22
  "fastmcp>=3.0",
23
23
  ]
@@ -1,3 +1,3 @@
1
1
  """squackit: Semi-QUalified Agent Companion Kit — the stateful intelligence + MCP server layer for fledgling-equipped agents."""
2
2
 
3
- __version__ = "0.3.2"
3
+ __version__ = "0.4.0"