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.
- {squackit-0.3.2 → squackit-0.4.0}/.gitignore +2 -0
- {squackit-0.3.2 → squackit-0.4.0}/PKG-INFO +2 -2
- {squackit-0.3.2 → squackit-0.4.0}/docs/architecture.md +42 -12
- {squackit-0.3.2 → squackit-0.4.0}/docs/configuration.md +7 -7
- {squackit-0.3.2 → squackit-0.4.0}/docs/index.md +24 -7
- squackit-0.4.0/docs/quickstart.md +172 -0
- {squackit-0.3.2 → squackit-0.4.0}/docs/tools.md +89 -62
- {squackit-0.3.2 → squackit-0.4.0}/pyproject.toml +2 -2
- {squackit-0.3.2 → squackit-0.4.0}/squackit/__init__.py +1 -1
- {squackit-0.3.2 → squackit-0.4.0}/squackit/cli.py +35 -5
- {squackit-0.3.2 → squackit-0.4.0}/squackit/server.py +9 -3
- squackit-0.4.0/squackit/tools.py +207 -0
- {squackit-0.3.2 → squackit-0.4.0}/tests/test_cli_tools.py +17 -0
- {squackit-0.3.2 → squackit-0.4.0}/tests/test_smoke.py +1 -1
- squackit-0.4.0/tests/test_tools.py +282 -0
- squackit-0.3.2/docs/quickstart.md +0 -104
- squackit-0.3.2/squackit/tools.py +0 -102
- squackit-0.3.2/tests/test_tools.py +0 -92
- {squackit-0.3.2 → squackit-0.4.0}/.github/workflows/release.yml +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/.mcp.json +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/.readthedocs.yaml +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/.readthedocs.yml +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/CLAUDE.md +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/LICENSE +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/README.md +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/docs/prompts.md +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/docs/resources.md +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/docs/superpowers/plans/2026-04-10-phase1-handoff.md +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/docs/superpowers/plans/2026-04-10-squawkit-extraction.md +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/docs/superpowers/plans/2026-04-11-phase3-pluckit-rewire.md +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/docs/superpowers/plans/2026-04-12-cli-tool-exposure.md +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/docs/superpowers/plans/2026-04-12-pluckit-tool-integration.md +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/docs/superpowers/plans/2026-04-12-session-handoff.md +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/docs/superpowers/specs/2026-04-10-squawkit-design.md +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/docs/superpowers/specs/2026-04-12-cli-tool-exposure-design.md +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/docs/superpowers/specs/2026-04-12-pluckit-tool-integration-design.md +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/mkdocs.yml +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/squackit/__main__.py +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/squackit/db.py +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/squackit/defaults.py +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/squackit/formatting.py +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/squackit/prompts.py +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/squackit/session.py +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/squackit/tool_config.py +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/squackit/workflows.py +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/tests/conftest.py +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/tests/test_defaults.py +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/tests/test_formatting_json.py +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/tests/test_prompts.py +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/tests/test_resources.py +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/tests/test_session.py +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/tests/test_tool_config.py +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/tests/test_truncation.py +0 -0
- {squackit-0.3.2 → squackit-0.4.0}/tests/test_workflows.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: squackit
|
|
3
|
-
Version: 0.
|
|
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.
|
|
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
|
-
│
|
|
23
|
-
│
|
|
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
|
|
40
|
-
fledgling Connection proxy
|
|
41
|
-
|
|
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
|
-
| `
|
|
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
|
|
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 "
|
|
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.
|
|
84
|
+
│ con.read_source(file_path=..., lines=...)
|
|
77
85
|
│ │
|
|
78
86
|
│ ▼
|
|
79
|
-
│
|
|
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
|
-
|
|
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`, `
|
|
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 (`
|
|
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
|
-
`
|
|
89
|
-
|
|
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="
|
|
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
|
-
|
|
15
|
+
squackit wears two hats: an MCP server for AI agents, and a CLI for humans.
|
|
16
16
|
|
|
17
|
-
|
|
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
|
|
22
|
-
- **Token-aware output** with configurable truncation
|
|
23
|
-
- **Session caching** with per-tool TTL policies and mtime-based invalidation
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
12
|
-
`
|
|
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
|
-
| `
|
|
17
|
-
| `
|
|
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
|
-
###
|
|
36
|
+
### find
|
|
20
37
|
|
|
21
|
-
|
|
22
|
-
|
|
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
|
-
| `
|
|
27
|
-
| `
|
|
28
|
-
| `name` | string | `%` | Name pattern to filter |
|
|
43
|
+
| `source` | string | required | Glob pattern for files |
|
|
44
|
+
| `selector` | string | required | CSS selector |
|
|
29
45
|
|
|
30
|
-
|
|
46
|
+
```bash
|
|
47
|
+
squackit tool find "src/**/*.py" ".fn"
|
|
48
|
+
squackit tool find "**/*.py" ".class > .fn"
|
|
49
|
+
```
|
|
31
50
|
|
|
32
|
-
|
|
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
|
-
| `
|
|
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
|
-
###
|
|
65
|
+
### complexity
|
|
39
66
|
|
|
40
|
-
|
|
67
|
+
Find AST nodes ranked by complexity (descendant count).
|
|
41
68
|
|
|
42
69
|
| Parameter | Type | Default | Description |
|
|
43
70
|
|-----------|------|---------|-------------|
|
|
44
|
-
| `
|
|
45
|
-
| `
|
|
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
|
-
| `
|
|
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
|
-
| `
|
|
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
|
-
| `
|
|
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 |
|
|
119
|
-
| `to_rev` | string |
|
|
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
|
-
| `
|
|
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
|
-
| `
|
|
138
|
-
| `rev` | string |
|
|
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 |
|
|
169
|
-
| `to_rev` | string |
|
|
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
|
-
|
|
214
|
+
## Conversation tools (MCP only)
|
|
175
215
|
|
|
176
|
-
|
|
216
|
+
These are registered on the MCP server but not exposed via CLI.
|
|
177
217
|
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
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
|
+
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.
|
|
20
|
+
"ast-pluckit>=0.9.0",
|
|
21
21
|
"click>=8.0",
|
|
22
22
|
"fastmcp>=3.0",
|
|
23
23
|
]
|