mirror of
https://github.com/cupcakearmy/nix-macos.git
synced 2026-11-22 11:03:42 +00:00
Compare commits
3
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
0c542cf80d | ||
|
|
c03dcd08a8 | ||
|
|
c010980921 |
@@ -0,0 +1,132 @@
|
|||||||
|
{
|
||||||
|
"version": 3,
|
||||||
|
"skills": {
|
||||||
|
"caveman": {
|
||||||
|
"source": "juliusbrussee/caveman",
|
||||||
|
"sourceType": "github",
|
||||||
|
"sourceUrl": "https://github.com/juliusbrussee/caveman.git",
|
||||||
|
"skillPath": "caveman/SKILL.md",
|
||||||
|
"skillFolderHash": "825e13085d1515fe67881b2123f3bf9b34c26154",
|
||||||
|
"installedAt": "2026-04-07T08:40:17.050Z",
|
||||||
|
"updatedAt": "2026-04-15T09:57:21.109Z"
|
||||||
|
},
|
||||||
|
"caveman-compress": {
|
||||||
|
"source": "JuliusBrussee/caveman",
|
||||||
|
"sourceType": "github",
|
||||||
|
"sourceUrl": "https://github.com/JuliusBrussee/caveman.git",
|
||||||
|
"skillPath": "caveman-compress/SKILL.md",
|
||||||
|
"skillFolderHash": "0c441d724eedf926f66c5a370ab74c38a9fd99a1",
|
||||||
|
"installedAt": "2026-04-07T08:40:17.465Z",
|
||||||
|
"updatedAt": "2026-04-07T08:40:41.747Z"
|
||||||
|
},
|
||||||
|
"find-skills": {
|
||||||
|
"source": "vercel-labs/skills",
|
||||||
|
"sourceType": "github",
|
||||||
|
"sourceUrl": "https://github.com/vercel-labs/skills.git",
|
||||||
|
"skillPath": "skills/find-skills/SKILL.md",
|
||||||
|
"skillFolderHash": "76a98a285cb0434f3d39e1a873823556330e398b",
|
||||||
|
"installedAt": "2026-04-07T08:40:26.035Z",
|
||||||
|
"updatedAt": "2026-11-10T12:00:01.015Z"
|
||||||
|
},
|
||||||
|
"karpathy-guidelines": {
|
||||||
|
"source": "forrestchang/andrej-karpathy-skills",
|
||||||
|
"sourceType": "github",
|
||||||
|
"sourceUrl": "https://github.com/forrestchang/andrej-karpathy-skills.git",
|
||||||
|
"skillPath": "skills/karpathy-guidelines/SKILL.md",
|
||||||
|
"skillFolderHash": "e119339197d600aa39a24fd7a95c946800c9c949",
|
||||||
|
"pluginName": "andrej-karpathy-skills",
|
||||||
|
"installedAt": "2026-04-15T09:56:29.882Z",
|
||||||
|
"updatedAt": "2026-04-15T09:56:29.882Z"
|
||||||
|
},
|
||||||
|
"caveman-commit": {
|
||||||
|
"source": "juliusbrussee/caveman",
|
||||||
|
"sourceType": "github",
|
||||||
|
"sourceUrl": "https://github.com/juliusbrussee/caveman.git",
|
||||||
|
"skillPath": "skills/caveman-commit/SKILL.md",
|
||||||
|
"skillFolderHash": "7b600195c1d3cdd277dc608c56384c86afb7ec11",
|
||||||
|
"installedAt": "2026-04-15T09:57:21.536Z",
|
||||||
|
"updatedAt": "2026-11-10T12:00:01.006Z"
|
||||||
|
},
|
||||||
|
"ast-grep": {
|
||||||
|
"source": "ast-grep/agent-skill",
|
||||||
|
"sourceType": "github",
|
||||||
|
"sourceUrl": "https://github.com/ast-grep/agent-skill.git",
|
||||||
|
"skillPath": "ast-grep/skills/ast-grep/SKILL.md",
|
||||||
|
"skillFolderHash": "6348724abcf567de5944e0ed0dfd7ec280ffced2",
|
||||||
|
"installedAt": "2026-04-15T10:05:19.680Z",
|
||||||
|
"updatedAt": "2026-11-10T12:00:01.037Z"
|
||||||
|
},
|
||||||
|
"ponytail": {
|
||||||
|
"source": "dietrichgebert/ponytail",
|
||||||
|
"sourceType": "github",
|
||||||
|
"sourceUrl": "https://github.com/dietrichgebert/ponytail.git",
|
||||||
|
"skillPath": "skills/ponytail/SKILL.md",
|
||||||
|
"skillFolderHash": "e8d3fa76e7ff9223a784dbd4bcfc9ff46b3fa55d",
|
||||||
|
"installedAt": "2026-06-23T14:05:25.784Z",
|
||||||
|
"updatedAt": "2026-11-10T12:00:01.060Z"
|
||||||
|
},
|
||||||
|
"ponytail-audit": {
|
||||||
|
"source": "dietrichgebert/ponytail",
|
||||||
|
"sourceType": "github",
|
||||||
|
"sourceUrl": "https://github.com/dietrichgebert/ponytail.git",
|
||||||
|
"skillPath": "skills/ponytail-audit/SKILL.md",
|
||||||
|
"skillFolderHash": "0c1468092a2b011b7acd369becea098f0c17f1c0",
|
||||||
|
"installedAt": "2026-06-23T14:05:25.787Z",
|
||||||
|
"updatedAt": "2026-11-10T12:00:01.082Z"
|
||||||
|
},
|
||||||
|
"ponytail-debt": {
|
||||||
|
"source": "dietrichgebert/ponytail",
|
||||||
|
"sourceType": "github",
|
||||||
|
"sourceUrl": "https://github.com/dietrichgebert/ponytail.git",
|
||||||
|
"skillPath": "skills/ponytail-debt/SKILL.md",
|
||||||
|
"skillFolderHash": "16c3b7953629510afa8f061f0fefa61a104e3020",
|
||||||
|
"installedAt": "2026-06-23T14:05:25.787Z",
|
||||||
|
"updatedAt": "2026-11-10T12:00:01.105Z"
|
||||||
|
},
|
||||||
|
"ponytail-gain": {
|
||||||
|
"source": "dietrichgebert/ponytail",
|
||||||
|
"sourceType": "github",
|
||||||
|
"sourceUrl": "https://github.com/dietrichgebert/ponytail.git",
|
||||||
|
"skillPath": "skills/ponytail-gain/SKILL.md",
|
||||||
|
"skillFolderHash": "c41e9e90173ddc6844c0bc44a89ba739534e06b0",
|
||||||
|
"installedAt": "2026-06-23T14:05:25.788Z",
|
||||||
|
"updatedAt": "2026-11-10T12:00:01.128Z"
|
||||||
|
},
|
||||||
|
"ponytail-help": {
|
||||||
|
"source": "dietrichgebert/ponytail",
|
||||||
|
"sourceType": "github",
|
||||||
|
"sourceUrl": "https://github.com/dietrichgebert/ponytail.git",
|
||||||
|
"skillPath": "skills/ponytail-help/SKILL.md",
|
||||||
|
"skillFolderHash": "f293d9e0ecff5da72cb4accf8a9e4717892cf0ad",
|
||||||
|
"installedAt": "2026-06-23T14:05:25.788Z",
|
||||||
|
"updatedAt": "2026-11-10T12:00:01.151Z"
|
||||||
|
},
|
||||||
|
"ponytail-review": {
|
||||||
|
"source": "dietrichgebert/ponytail",
|
||||||
|
"sourceType": "github",
|
||||||
|
"sourceUrl": "https://github.com/dietrichgebert/ponytail.git",
|
||||||
|
"skillPath": "skills/ponytail-review/SKILL.md",
|
||||||
|
"skillFolderHash": "8ad8430c42a6f8cd18758dddb70cfee399725de6",
|
||||||
|
"installedAt": "2026-06-23T14:05:25.789Z",
|
||||||
|
"updatedAt": "2026-11-10T12:00:01.180Z"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"dismissed": {
|
||||||
|
"findSkillsPrompt": true
|
||||||
|
},
|
||||||
|
"lastSelectedAgents": [
|
||||||
|
"amp",
|
||||||
|
"antigravity",
|
||||||
|
"antigravity-cli",
|
||||||
|
"cline",
|
||||||
|
"codex",
|
||||||
|
"cursor",
|
||||||
|
"deepagents",
|
||||||
|
"gemini-cli",
|
||||||
|
"github-copilot",
|
||||||
|
"kimi-code-cli",
|
||||||
|
"opencode",
|
||||||
|
"warp",
|
||||||
|
"zed"
|
||||||
|
]
|
||||||
|
}
|
||||||
@@ -0,0 +1,8 @@
|
|||||||
|
# User defaults
|
||||||
|
|
||||||
|
Please always use the following rules unless specified otherwise, or turned off later:
|
||||||
|
|
||||||
|
- caveman
|
||||||
|
- caveman-commit
|
||||||
|
- karpathy-guidelines
|
||||||
|
- ast-grep
|
||||||
@@ -0,0 +1,365 @@
|
|||||||
|
---
|
||||||
|
name: ast-grep
|
||||||
|
description: Guide for writing ast-grep rules to perform structural code search and analysis. Use when users need to search codebases using Abstract Syntax Tree (AST) patterns, find specific code structures, or perform complex code queries that go beyond simple text search. This skill should be used when users ask to search for code patterns, find specific language constructs, or locate code with particular structural characteristics.
|
||||||
|
---
|
||||||
|
|
||||||
|
# ast-grep Code Search
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
This skill helps translate natural language queries into ast-grep rules for structural code search. ast-grep uses Abstract Syntax Tree (AST) patterns to match code based on its structure rather than just text, enabling powerful and precise code search across large codebases.
|
||||||
|
|
||||||
|
## When to Use This Skill
|
||||||
|
|
||||||
|
Use this skill when users:
|
||||||
|
- Need to search for code patterns using structural matching (e.g., "find all async functions that don't have error handling")
|
||||||
|
- Want to locate specific language constructs (e.g., "find all function calls with specific parameters")
|
||||||
|
- Request searches that require understanding code structure rather than just text
|
||||||
|
- Ask to search for code with particular AST characteristics
|
||||||
|
- Need to perform complex code queries that traditional text search cannot handle
|
||||||
|
|
||||||
|
## General Workflow
|
||||||
|
|
||||||
|
Follow this process to help users write effective ast-grep rules:
|
||||||
|
|
||||||
|
### Step 1: Understand the Query
|
||||||
|
|
||||||
|
Clearly understand what the user wants to find. Ask clarifying questions if needed:
|
||||||
|
- What specific code pattern or structure are they looking for?
|
||||||
|
- Which programming language?
|
||||||
|
- Are there specific edge cases or variations to consider?
|
||||||
|
- What should be included or excluded from matches?
|
||||||
|
|
||||||
|
### Step 2: Create Example Code
|
||||||
|
|
||||||
|
Write a simple code snippet that represents what the user wants to match. Save this to a temporary file for testing.
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
If searching for "async functions that use await", create a test file:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// test_example.js
|
||||||
|
async function example() {
|
||||||
|
const result = await fetchData();
|
||||||
|
return result;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 3: Write the ast-grep Rule
|
||||||
|
|
||||||
|
Translate the pattern into an ast-grep rule. Start simple and add complexity as needed.
|
||||||
|
|
||||||
|
**Key principles:**
|
||||||
|
- Always use `stopBy: end` for relational rules (`inside`, `has`) to ensure search goes to the end of the direction
|
||||||
|
- Use `pattern` for simple structures
|
||||||
|
- Use `kind` with `has`/`inside` for complex structures
|
||||||
|
- Break complex queries into smaller sub-rules using `all`, `any`, or `not`
|
||||||
|
|
||||||
|
**Example rule file (test_rule.yml):**
|
||||||
|
```yaml
|
||||||
|
id: async-with-await
|
||||||
|
language: javascript
|
||||||
|
rule:
|
||||||
|
kind: function_declaration
|
||||||
|
has:
|
||||||
|
pattern: await $EXPR
|
||||||
|
stopBy: end
|
||||||
|
```
|
||||||
|
|
||||||
|
See `references/rule_reference.md` for comprehensive rule documentation.
|
||||||
|
|
||||||
|
### Step 4: Test the Rule
|
||||||
|
|
||||||
|
Use ast-grep CLI to verify the rule matches the example code. There are two main approaches:
|
||||||
|
|
||||||
|
**Option A: Test with inline rules (for quick iterations)**
|
||||||
|
```bash
|
||||||
|
echo "async function test() { await fetch(); }" | ast-grep scan --inline-rules "id: test
|
||||||
|
language: javascript
|
||||||
|
rule:
|
||||||
|
kind: function_declaration
|
||||||
|
has:
|
||||||
|
pattern: await \$EXPR
|
||||||
|
stopBy: end" --stdin
|
||||||
|
```
|
||||||
|
|
||||||
|
**Option B: Test with rule files (recommended for complex rules)**
|
||||||
|
```bash
|
||||||
|
ast-grep scan --rule test_rule.yml test_example.js
|
||||||
|
```
|
||||||
|
|
||||||
|
**Debugging if no matches:**
|
||||||
|
1. Simplify the rule (remove sub-rules)
|
||||||
|
2. Add `stopBy: end` to relational rules if not present
|
||||||
|
3. Use `--debug-query` to understand the AST structure (see below)
|
||||||
|
4. Check if `kind` values are correct for the language
|
||||||
|
5. For zero matches from `run --pattern` (not rules), see the "Zero Matches?" tip below
|
||||||
|
|
||||||
|
### Step 5: Search the Codebase
|
||||||
|
|
||||||
|
Once the rule matches the example code correctly, search the actual codebase:
|
||||||
|
|
||||||
|
**For simple pattern searches:**
|
||||||
|
```bash
|
||||||
|
ast-grep run --pattern 'console.log($ARG)' --lang javascript /path/to/project
|
||||||
|
```
|
||||||
|
|
||||||
|
**For complex rule-based searches:**
|
||||||
|
```bash
|
||||||
|
ast-grep scan --rule my_rule.yml /path/to/project
|
||||||
|
```
|
||||||
|
|
||||||
|
**For inline rules (without creating files):**
|
||||||
|
```bash
|
||||||
|
ast-grep scan --inline-rules "id: my-rule
|
||||||
|
language: javascript
|
||||||
|
rule:
|
||||||
|
pattern: \$PATTERN" /path/to/project
|
||||||
|
```
|
||||||
|
|
||||||
|
## ast-grep CLI Commands
|
||||||
|
|
||||||
|
### Inspect Code Structure (--debug-query)
|
||||||
|
|
||||||
|
Dump the AST structure to understand how code is parsed:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ast-grep run --pattern 'async function example() { await fetch(); }' \
|
||||||
|
--lang javascript \
|
||||||
|
--debug-query=cst
|
||||||
|
```
|
||||||
|
|
||||||
|
**Available formats:**
|
||||||
|
- `cst`: Concrete Syntax Tree (shows all nodes including punctuation)
|
||||||
|
- `ast`: Abstract Syntax Tree (shows only named nodes)
|
||||||
|
- `pattern`: Shows how ast-grep interprets your pattern
|
||||||
|
|
||||||
|
**Use this to:**
|
||||||
|
- Find the correct `kind` values for nodes
|
||||||
|
- Understand the structure of code you want to match
|
||||||
|
- Debug why patterns aren't matching
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```bash
|
||||||
|
# See the structure of your target code
|
||||||
|
ast-grep run --pattern 'class User { constructor() {} }' \
|
||||||
|
--lang javascript \
|
||||||
|
--debug-query=cst
|
||||||
|
|
||||||
|
# See how ast-grep interprets your pattern
|
||||||
|
ast-grep run --pattern 'class $NAME { $$$BODY }' \
|
||||||
|
--lang javascript \
|
||||||
|
--debug-query=pattern
|
||||||
|
```
|
||||||
|
|
||||||
|
### Test Rules (scan with --stdin)
|
||||||
|
|
||||||
|
Test a rule against code snippet without creating files:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
echo "const x = await fetch();" | ast-grep scan --inline-rules "id: test
|
||||||
|
language: javascript
|
||||||
|
rule:
|
||||||
|
pattern: await \$EXPR" --stdin
|
||||||
|
```
|
||||||
|
|
||||||
|
**Add --json for structured output:**
|
||||||
|
```bash
|
||||||
|
echo "const x = await fetch();" | ast-grep scan --inline-rules "..." --stdin --json
|
||||||
|
```
|
||||||
|
|
||||||
|
### Search with Patterns (run)
|
||||||
|
|
||||||
|
Simple pattern-based search for single AST node matches:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Basic pattern search
|
||||||
|
ast-grep run --pattern 'console.log($ARG)' --lang javascript .
|
||||||
|
|
||||||
|
# Search specific files
|
||||||
|
ast-grep run --pattern 'class $NAME' --lang python /path/to/project
|
||||||
|
|
||||||
|
# JSON output for programmatic use
|
||||||
|
ast-grep run --pattern 'function $NAME($$$)' --lang javascript --json .
|
||||||
|
```
|
||||||
|
|
||||||
|
**When to use:**
|
||||||
|
- Simple, single-node matches
|
||||||
|
- Quick searches without complex logic
|
||||||
|
- When you don't need relational rules (inside/has)
|
||||||
|
|
||||||
|
### Reading `--json` Output
|
||||||
|
|
||||||
|
`--json` prints a bare JSON **array** of matches (no `matches` wrapper). For pattern `foo($ARG, $$$REST)`:
|
||||||
|
|
||||||
|
```json
|
||||||
|
[{
|
||||||
|
"text": "foo(\"value\", 1, 2)",
|
||||||
|
"file": "src/app.js",
|
||||||
|
"range": { "start": { "line": 41, "column": 10 }, "end": { "line": 41, "column": 27 } },
|
||||||
|
"metaVariables": {
|
||||||
|
"single": { "ARG": { "text": "\"value\"" } },
|
||||||
|
"multi": { "REST": [ { "text": "1" }, { "text": "2" } ] }
|
||||||
|
}
|
||||||
|
}]
|
||||||
|
```
|
||||||
|
|
||||||
|
`scan --json` uses the same schema.
|
||||||
|
|
||||||
|
(Each match also includes `lines` and `language`.) `range.start.line` is 0-based. Named metavariables (`$ARG`) land in `single`, list metavariables (`$$$REST`) in `multi` as a list (empty if nothing captured). Extract with jq:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ast-grep run --pattern 'foo($ARG)' --lang javascript --json . \
|
||||||
|
| jq -r '.[] | "\(.file):\(.range.start.line + 1): \(.metaVariables.single.ARG.text)"'
|
||||||
|
```
|
||||||
|
|
||||||
|
### Search with Rules (scan)
|
||||||
|
|
||||||
|
YAML rule-based search for complex structural queries:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# With rule file
|
||||||
|
ast-grep scan --rule my_rule.yml /path/to/project
|
||||||
|
|
||||||
|
# With inline rules
|
||||||
|
ast-grep scan --inline-rules "id: find-async
|
||||||
|
language: javascript
|
||||||
|
rule:
|
||||||
|
kind: function_declaration
|
||||||
|
has:
|
||||||
|
pattern: await \$EXPR
|
||||||
|
stopBy: end" /path/to/project
|
||||||
|
|
||||||
|
# JSON output
|
||||||
|
ast-grep scan --rule my_rule.yml --json /path/to/project
|
||||||
|
```
|
||||||
|
|
||||||
|
**When to use:**
|
||||||
|
- Complex structural searches
|
||||||
|
- Relational rules (inside, has, precedes, follows)
|
||||||
|
- Composite logic (all, any, not)
|
||||||
|
- When you need the power of full YAML rules
|
||||||
|
|
||||||
|
**Tip:** For relational rules (inside/has), always add `stopBy: end` to ensure complete traversal.
|
||||||
|
|
||||||
|
## Tips for Writing Effective Rules
|
||||||
|
|
||||||
|
### Always Use stopBy: end
|
||||||
|
|
||||||
|
For relational rules, always use `stopBy: end` unless there's a specific reason not to:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
has:
|
||||||
|
pattern: await $EXPR
|
||||||
|
stopBy: end
|
||||||
|
```
|
||||||
|
|
||||||
|
This ensures the search traverses the entire subtree rather than stopping at the first non-matching node.
|
||||||
|
|
||||||
|
### Start Simple, Then Add Complexity
|
||||||
|
|
||||||
|
Begin with the simplest rule that could work:
|
||||||
|
1. Try a `pattern` first
|
||||||
|
2. If that doesn't work, try `kind` to match the node type
|
||||||
|
3. Add relational rules (`has`, `inside`) as needed
|
||||||
|
4. Combine with composite rules (`all`, `any`, `not`) for complex logic
|
||||||
|
|
||||||
|
### Use the Right Rule Type
|
||||||
|
|
||||||
|
- **Pattern**: For simple, direct code matching (e.g., `console.log($ARG)`)
|
||||||
|
- **Kind + Relational**: For complex structures (e.g., "function containing await")
|
||||||
|
- **Composite**: For logical combinations (e.g., "function with await but not in try-catch")
|
||||||
|
|
||||||
|
### Debug with AST Inspection
|
||||||
|
|
||||||
|
When rules don't match:
|
||||||
|
1. Use `--debug-query=cst` to see the actual AST structure
|
||||||
|
2. Check if metavariables are being detected correctly
|
||||||
|
3. Verify the node `kind` matches what you expect
|
||||||
|
4. Ensure relational rules are searching in the right direction
|
||||||
|
|
||||||
|
### Zero Matches? Patterns Match Whole AST Nodes
|
||||||
|
|
||||||
|
`run --pattern` matches complete AST nodes, not text substrings, so zero matches can mean "code absent" or "pattern has the wrong node shape":
|
||||||
|
|
||||||
|
- Qualified paths are whole nodes: `env::var($ENV)` does NOT match `std::env::var("X")`. Try both bare and fully-qualified forms, or use `$$$` to absorb extra intermediate nodes.
|
||||||
|
- To tell them apart: test the pattern on a snippet known to contain the code, and inspect how ast-grep parsed it with `--debug-query=pattern` (works for `run`, not just `scan`/rules). For zero matches from rules instead, follow the Step 4 debugging checklist.
|
||||||
|
|
||||||
|
### Escaping in Inline Rules
|
||||||
|
|
||||||
|
When using `--inline-rules`, escape metavariables in shell commands:
|
||||||
|
- Use `\$VAR` instead of `$VAR` (shell interprets `$` as variable)
|
||||||
|
- Or use single quotes: `'$VAR'` works in most shells
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```bash
|
||||||
|
# Correct: escaped $
|
||||||
|
ast-grep scan --inline-rules "rule: {pattern: 'console.log(\$ARG)'}" .
|
||||||
|
|
||||||
|
# Or use single quotes
|
||||||
|
ast-grep scan --inline-rules 'rule: {pattern: "console.log($ARG)"}' .
|
||||||
|
```
|
||||||
|
|
||||||
|
## Common Use Cases
|
||||||
|
|
||||||
|
### Find Functions with Specific Content
|
||||||
|
|
||||||
|
Find async functions that use await:
|
||||||
|
```bash
|
||||||
|
ast-grep scan --inline-rules "id: async-await
|
||||||
|
language: javascript
|
||||||
|
rule:
|
||||||
|
all:
|
||||||
|
- kind: function_declaration
|
||||||
|
- has:
|
||||||
|
pattern: await \$EXPR
|
||||||
|
stopBy: end" /path/to/project
|
||||||
|
```
|
||||||
|
|
||||||
|
### Find Code Inside Specific Contexts
|
||||||
|
|
||||||
|
Find console.log inside class methods:
|
||||||
|
```bash
|
||||||
|
ast-grep scan --inline-rules "id: console-in-class
|
||||||
|
language: javascript
|
||||||
|
rule:
|
||||||
|
pattern: console.log(\$\$\$)
|
||||||
|
inside:
|
||||||
|
kind: method_definition
|
||||||
|
stopBy: end" /path/to/project
|
||||||
|
```
|
||||||
|
|
||||||
|
### Find Code Missing Expected Patterns
|
||||||
|
|
||||||
|
Find async functions without try-catch:
|
||||||
|
```bash
|
||||||
|
ast-grep scan --inline-rules "id: async-no-trycatch
|
||||||
|
language: javascript
|
||||||
|
rule:
|
||||||
|
all:
|
||||||
|
- kind: function_declaration
|
||||||
|
- has:
|
||||||
|
pattern: await \$EXPR
|
||||||
|
stopBy: end
|
||||||
|
- not:
|
||||||
|
has:
|
||||||
|
pattern: try { \$\$\$ } catch (\$E) { \$\$\$ }
|
||||||
|
stopBy: end" /path/to/project
|
||||||
|
```
|
||||||
|
|
||||||
|
## Resources
|
||||||
|
|
||||||
|
### references/
|
||||||
|
Contains detailed documentation for ast-grep rule syntax:
|
||||||
|
- `rule_reference.md`: Comprehensive ast-grep rule documentation covering atomic rules, relational rules, composite rules, and metavariables
|
||||||
|
|
||||||
|
Load these references when detailed rule syntax information is needed.
|
||||||
|
|
||||||
|
### Online documentation
|
||||||
|
When a rule still fails after `--debug-query` and the rule reference, read
|
||||||
|
the official docs:
|
||||||
|
- `https://ast-grep.github.io/llms.txt` indexes every docs page; fetch the
|
||||||
|
one page you need (each is linked as a `.md` file, such as
|
||||||
|
`https://ast-grep.github.io/guide/rule-config/relational-rule.md`).
|
||||||
|
- `https://ast-grep.github.io/llms-full.txt` holds all the docs in one
|
||||||
|
file of about 850 KB. Download it and search it; never read it whole.
|
||||||
@@ -0,0 +1,297 @@
|
|||||||
|
# ast-grep Rule Reference
|
||||||
|
|
||||||
|
This document provides comprehensive documentation for ast-grep rule syntax, covering all rule types and metavariables.
|
||||||
|
|
||||||
|
## Introduction to ast-grep Rules
|
||||||
|
|
||||||
|
ast-grep rules are declarative specifications for matching and filtering Abstract Syntax Tree (AST) nodes. They enable structural code search and analysis by defining conditions an AST node must meet to be matched.
|
||||||
|
|
||||||
|
### Rule Categories
|
||||||
|
|
||||||
|
ast-grep rules are categorized into three types:
|
||||||
|
|
||||||
|
* **Atomic Rules**: Match individual AST nodes based on intrinsic properties like code patterns (`pattern`), node type (`kind`), or text content (`regex`).
|
||||||
|
* **Relational Rules**: Define conditions based on a target node's position or relationship to other nodes (e.g., `inside`, `has`, `precedes`, `follows`).
|
||||||
|
* **Composite Rules**: Combine other rules using logical operations (AND, OR, NOT) to form complex matching criteria (e.g., `all`, `any`, `not`, `matches`).
|
||||||
|
|
||||||
|
## Anatomy of an ast-grep Rule Object
|
||||||
|
|
||||||
|
The ast-grep rule object is the core configuration unit defining how ast-grep identifies and filters AST nodes. It's typically written in YAML format.
|
||||||
|
|
||||||
|
### General Structure
|
||||||
|
|
||||||
|
Every field within an ast-grep Rule Object is optional, but at least one "positive" key (e.g., `kind`, `pattern`) must be present.
|
||||||
|
|
||||||
|
A node matches a rule if it satisfies all fields defined within that rule object, implying an implicit logical AND operation.
|
||||||
|
|
||||||
|
For rules using metavariables that depend on prior matching, explicit `all` composite rules are recommended to guarantee execution order.
|
||||||
|
|
||||||
|
### Rule Object Properties
|
||||||
|
|
||||||
|
| Property | Type | Category | Purpose | Example |
|
||||||
|
| :--- | :--- | :--- | :--- | :--- |
|
||||||
|
| `pattern` | String or Object | Atomic | Matches AST node by code pattern. | `pattern: console.log($ARG)` |
|
||||||
|
| `kind` | String | Atomic | Matches AST node by its kind name. | `kind: call_expression` |
|
||||||
|
| `regex` | String | Atomic | Matches node's text by Rust regex. | `regex: ^[a-z]+$` |
|
||||||
|
| `nthChild` | number, string, Object | Atomic | Matches nodes by their index within parent's children. | `nthChild: 1` |
|
||||||
|
| `range` | RangeObject | Atomic | Matches node by character-based start/end positions. | `range: { start: { line: 0, column: 0 }, end: { line: 0, column: 10 } }` |
|
||||||
|
| `inside` | Object | Relational | Target node must be inside node matching sub-rule. | `inside: { pattern: class $C { $$$ }, stopBy: end }` |
|
||||||
|
| `has` | Object | Relational | Target node must have descendant matching sub-rule. | `has: { pattern: await $EXPR, stopBy: end }` |
|
||||||
|
| `precedes` | Object | Relational | Target node must appear before node matching sub-rule. | `precedes: { pattern: return $VAL }` |
|
||||||
|
| `follows` | Object | Relational | Target node must appear after node matching sub-rule. | `follows: { pattern: import $M from '$P' }` |
|
||||||
|
| `all` | Array<Rule> | Composite | Matches if all sub-rules match. | `all: [ { kind: call_expression }, { pattern: foo($A) } ]` |
|
||||||
|
| `any` | Array<Rule> | Composite | Matches if any sub-rules match. | `any: [ { pattern: foo() }, { pattern: bar() } ]` |
|
||||||
|
| `not` | Object | Composite | Matches if sub-rule does not match. | `not: { pattern: console.log($ARG) }` |
|
||||||
|
| `matches` | String | Composite | Matches if predefined utility rule matches. | `matches: my-utility-rule-id` |
|
||||||
|
|
||||||
|
## Atomic Rules
|
||||||
|
|
||||||
|
Atomic rules match individual AST nodes based on their intrinsic properties.
|
||||||
|
|
||||||
|
### pattern: String and Object Forms
|
||||||
|
|
||||||
|
The `pattern` rule matches a single AST node based on a code pattern.
|
||||||
|
|
||||||
|
**String Pattern**: Directly matches using ast-grep's pattern syntax with metavariables.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
pattern: console.log($ARG)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Object Pattern**: Offers granular control for ambiguous patterns or specific contexts.
|
||||||
|
|
||||||
|
* `selector`: Pinpoints a specific part of the parsed pattern to match.
|
||||||
|
```yaml
|
||||||
|
pattern:
|
||||||
|
selector: field_definition
|
||||||
|
context: class { $F }
|
||||||
|
```
|
||||||
|
|
||||||
|
* `context`: Provides surrounding code context for correct parsing.
|
||||||
|
|
||||||
|
* `strictness`: Modifies the pattern's matching algorithm (`cst`, `smart`, `ast`, `relaxed`, `signature`).
|
||||||
|
```yaml
|
||||||
|
pattern:
|
||||||
|
context: foo($BAR)
|
||||||
|
strictness: relaxed
|
||||||
|
```
|
||||||
|
|
||||||
|
### kind: Matching by Node Type
|
||||||
|
|
||||||
|
The `kind` rule matches an AST node by its `tree_sitter_node_kind` name, derived from the language's Tree-sitter grammar. Useful for targeting constructs like `call_expression` or `function_declaration`.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
kind: call_expression
|
||||||
|
```
|
||||||
|
|
||||||
|
### regex: Text-Based Node Matching
|
||||||
|
|
||||||
|
The `regex` rule matches the entire text content of an AST node using a Rust regular expression. It's not a "positive" rule, meaning it matches any node whose text satisfies the regex, regardless of its structural kind.
|
||||||
|
|
||||||
|
### nthChild: Positional Node Matching
|
||||||
|
|
||||||
|
The `nthChild` rule finds nodes by their 1-based index within their parent's children list, counting only named nodes by default.
|
||||||
|
|
||||||
|
* `number`: Matches the exact nth child. Example: `nthChild: 1`
|
||||||
|
* `string`: Matches positions using An+B formula. Example: `2n+1`
|
||||||
|
* `Object`: Provides granular control:
|
||||||
|
* `position`: `number` or An+B string.
|
||||||
|
* `reverse`: `true` to count from the end.
|
||||||
|
* `ofRule`: An ast-grep rule to filter the sibling list before counting.
|
||||||
|
|
||||||
|
### range: Position-Based Node Matching
|
||||||
|
|
||||||
|
The `range` rule matches an AST node based on its character-based start and end positions. A `RangeObject` defines `start` and `end` fields, each with 0-based `line` and `column`. `start` is inclusive, `end` is exclusive.
|
||||||
|
|
||||||
|
## Relational Rules
|
||||||
|
|
||||||
|
Relational rules filter targets based on their position relative to other AST nodes. They can include `stopBy` and `field` options.
|
||||||
|
|
||||||
|
### inside: Matching Within a Parent Node
|
||||||
|
|
||||||
|
Requires the target node to be inside another node matching the `inside` sub-rule.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
inside:
|
||||||
|
pattern: class $C { $$$ }
|
||||||
|
stopBy: end
|
||||||
|
```
|
||||||
|
|
||||||
|
### has: Matching with a Descendant Node
|
||||||
|
|
||||||
|
Requires the target node to have a descendant node matching the `has` sub-rule.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
has:
|
||||||
|
pattern: await $EXPR
|
||||||
|
stopBy: end
|
||||||
|
```
|
||||||
|
|
||||||
|
### precedes and follows: Sequential Node Matching
|
||||||
|
|
||||||
|
* `precedes`: Target node must appear before a node matching the `precedes` sub-rule.
|
||||||
|
* `follows`: Target node must appear after a node matching the `follows` sub-rule.
|
||||||
|
|
||||||
|
Both include `stopBy` but not `field`.
|
||||||
|
|
||||||
|
### stopBy and field: Refining Relational Searches
|
||||||
|
|
||||||
|
**stopBy**: Controls search termination for relational rules.
|
||||||
|
|
||||||
|
* `"neighbor"` (default): Stops when immediate surrounding node doesn't match.
|
||||||
|
* `"end"`: Searches to the end of the direction (root for `inside`, leaf for `has`).
|
||||||
|
* `Rule object`: Stops when a surrounding node matches the provided rule (inclusive).
|
||||||
|
|
||||||
|
**field**: Specifies a sub-node within the target node that should match the relational rule. Only for `inside` and `has`.
|
||||||
|
|
||||||
|
**Best Practice**: When unsure, always use `stopBy: end` to ensure the search goes to the end of the direction.
|
||||||
|
|
||||||
|
## Composite Rules
|
||||||
|
|
||||||
|
Composite rules combine atomic and relational rules using logical operations.
|
||||||
|
|
||||||
|
### all: Conjunction (AND) of Rules
|
||||||
|
|
||||||
|
Matches a node only if all sub-rules in the list match. Guarantees order of rule matching, important for metavariables.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
all:
|
||||||
|
- kind: call_expression
|
||||||
|
- pattern: console.log($ARG)
|
||||||
|
```
|
||||||
|
|
||||||
|
### any: Disjunction (OR) of Rules
|
||||||
|
|
||||||
|
Matches a node if any sub-rules in the list match.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
any:
|
||||||
|
- pattern: console.log($ARG)
|
||||||
|
- pattern: console.warn($ARG)
|
||||||
|
- pattern: console.error($ARG)
|
||||||
|
```
|
||||||
|
|
||||||
|
### not: Negation (NOT) of a Rule
|
||||||
|
|
||||||
|
Matches a node if the single sub-rule does not match.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
not:
|
||||||
|
pattern: console.log($ARG)
|
||||||
|
```
|
||||||
|
|
||||||
|
### matches: Rule Reuse and Utility Rules
|
||||||
|
|
||||||
|
Takes a rule-id string, matching if the referenced utility rule matches. Enables rule reuse and recursive rules.
|
||||||
|
|
||||||
|
## Metavariables
|
||||||
|
|
||||||
|
Metavariables are placeholders in patterns to match dynamic content in the AST.
|
||||||
|
|
||||||
|
### $VAR: Single Named Node Capture
|
||||||
|
|
||||||
|
Captures a single named node in the AST.
|
||||||
|
|
||||||
|
* **Valid**: `$META`, `$META_VAR`, `$_`
|
||||||
|
* **Invalid**: `$invalid`, `$123`, `$KEBAB-CASE`
|
||||||
|
* **Example**: `console.log($GREETING)` matches `console.log('Hello World')`.
|
||||||
|
* **Reuse**: `$A == $A` matches `a == a` but not `a == b`.
|
||||||
|
|
||||||
|
### $$VAR: Single Unnamed Node Capture
|
||||||
|
|
||||||
|
Captures a single unnamed node (e.g., operators, punctuation).
|
||||||
|
|
||||||
|
**Example**: To match the operator in `a + b`, use `$$OP`.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
rule:
|
||||||
|
kind: binary_expression
|
||||||
|
has:
|
||||||
|
field: operator
|
||||||
|
pattern: $$OP
|
||||||
|
```
|
||||||
|
|
||||||
|
### $$$MULTI_META_VARIABLE: Multi-Node Capture
|
||||||
|
|
||||||
|
Matches zero or more AST nodes (non-greedy). Useful for variable numbers of arguments or statements.
|
||||||
|
|
||||||
|
* **Example**: `console.log($$$)` matches `console.log()`, `console.log('hello')`, and `console.log('debug:', key, value)`.
|
||||||
|
* **Example**: `function $FUNC($$$ARGS) { $$$ }` matches functions with varying parameters/statements.
|
||||||
|
|
||||||
|
### Non-Capturing Metavariables (_VAR)
|
||||||
|
|
||||||
|
Metavariables starting with an underscore (`_`) are not captured. They can match different content even if named identically, optimizing performance.
|
||||||
|
|
||||||
|
* **Example**: `$_FUNC($_FUNC)` matches `test(a)` and `testFunc(1 + 1)`.
|
||||||
|
|
||||||
|
### Important Considerations for Metavariable Detection
|
||||||
|
|
||||||
|
* **Syntax Matching**: Only exact metavariable syntax (e.g., `$A`, `$$B`, `$$$C`) is recognized.
|
||||||
|
* **Exclusive Content**: Metavariable text must be the only text within an AST node.
|
||||||
|
* **Non-working**: `obj.on$EVENT`, `"Hello $WORLD"`, `a $OP b`, `$jq`.
|
||||||
|
|
||||||
|
The ast-grep playground is useful for debugging patterns and visualizing metavariables.
|
||||||
|
|
||||||
|
## Common Patterns and Examples
|
||||||
|
|
||||||
|
### Finding Functions with Specific Content
|
||||||
|
|
||||||
|
Find functions that contain await expressions:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
rule:
|
||||||
|
kind: function_declaration
|
||||||
|
has:
|
||||||
|
pattern: await $EXPR
|
||||||
|
stopBy: end
|
||||||
|
```
|
||||||
|
|
||||||
|
### Finding Code Inside Specific Contexts
|
||||||
|
|
||||||
|
Find console.log calls inside class methods:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
rule:
|
||||||
|
pattern: console.log($$$)
|
||||||
|
inside:
|
||||||
|
kind: method_definition
|
||||||
|
stopBy: end
|
||||||
|
```
|
||||||
|
|
||||||
|
### Combining Multiple Conditions
|
||||||
|
|
||||||
|
Find async functions that use await but don't have try-catch:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
rule:
|
||||||
|
all:
|
||||||
|
- kind: function_declaration
|
||||||
|
- has:
|
||||||
|
pattern: await $EXPR
|
||||||
|
stopBy: end
|
||||||
|
- not:
|
||||||
|
has:
|
||||||
|
pattern: try { $$$ } catch ($E) { $$$ }
|
||||||
|
stopBy: end
|
||||||
|
```
|
||||||
|
|
||||||
|
### Matching Multiple Alternatives
|
||||||
|
|
||||||
|
Find any type of console method call:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
rule:
|
||||||
|
any:
|
||||||
|
- pattern: console.log($$$)
|
||||||
|
- pattern: console.warn($$$)
|
||||||
|
- pattern: console.error($$$)
|
||||||
|
- pattern: console.debug($$$)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Troubleshooting Tips
|
||||||
|
|
||||||
|
1. **Rule doesn't match**: Use `dump_syntax_tree` to see the actual AST structure
|
||||||
|
2. **Relational rule issues**: Ensure `stopBy: end` is set for deep searches
|
||||||
|
3. **Wrong node kind**: Check the language's Tree-sitter grammar for correct kind names
|
||||||
|
4. **Metavariable not working**: Ensure it's the only content in its AST node
|
||||||
|
5. **Pattern too complex**: Break it down into simpler sub-rules using `all`
|
||||||
@@ -0,0 +1,44 @@
|
|||||||
|
# caveman-commit
|
||||||
|
|
||||||
|
Terse Conventional Commits. Why over what.
|
||||||
|
|
||||||
|
## What it does
|
||||||
|
|
||||||
|
Generates commit messages in Conventional Commits format. Subject ≤50 chars, hard cap 72. Imperative mood. Body only when the *why* is non-obvious or there are breaking changes. No AI attribution, no "this commit does X", no emoji unless the project uses them. Body always required for breaking changes, security fixes, data migrations, and reverts — future debuggers need the context.
|
||||||
|
|
||||||
|
Outputs only the message. Does not stage, commit, or amend.
|
||||||
|
|
||||||
|
## How to invoke
|
||||||
|
|
||||||
|
```
|
||||||
|
/caveman-commit
|
||||||
|
```
|
||||||
|
|
||||||
|
Also triggers on phrases like "write a commit", "commit message", "generate commit".
|
||||||
|
|
||||||
|
## Example output
|
||||||
|
|
||||||
|
Diff: new endpoint for user profile.
|
||||||
|
|
||||||
|
```
|
||||||
|
feat(api): add GET /users/:id/profile
|
||||||
|
|
||||||
|
Mobile client needs profile data without the full user payload
|
||||||
|
to reduce LTE bandwidth on cold-launch screens.
|
||||||
|
|
||||||
|
Closes #128
|
||||||
|
```
|
||||||
|
|
||||||
|
Diff: breaking API rename.
|
||||||
|
|
||||||
|
```
|
||||||
|
feat(api)!: rename /v1/orders to /v1/checkout
|
||||||
|
|
||||||
|
BREAKING CHANGE: clients on /v1/orders must migrate to /v1/checkout
|
||||||
|
before 2026-06-01. Old route returns 410 after that date.
|
||||||
|
```
|
||||||
|
|
||||||
|
## See also
|
||||||
|
|
||||||
|
- [`SKILL.md`](./SKILL.md) — full LLM-facing instructions
|
||||||
|
- [Caveman README](../../README.md) — repo overview
|
||||||
@@ -0,0 +1,63 @@
|
|||||||
|
---
|
||||||
|
name: caveman-commit
|
||||||
|
description: >
|
||||||
|
Write a Conventional Commits message compressed to intent only. Use for
|
||||||
|
"write a commit", "commit message", /commit or /caveman-commit.
|
||||||
|
---
|
||||||
|
|
||||||
|
Write commit messages terse and exact. Conventional Commits format. No fluff. Why over what.
|
||||||
|
|
||||||
|
## Rules
|
||||||
|
|
||||||
|
**Subject line:**
|
||||||
|
- `<type>(<scope>): <imperative summary>` — `<scope>` optional
|
||||||
|
- Types: `feat`, `fix`, `refactor`, `perf`, `docs`, `test`, `chore`, `build`, `ci`, `style`, `revert`
|
||||||
|
- Imperative mood: "add", "fix", "remove" — not "added", "adds", "adding"
|
||||||
|
- ≤50 chars when possible, hard cap 72
|
||||||
|
- No trailing period
|
||||||
|
- Match project convention for capitalization after the colon
|
||||||
|
|
||||||
|
**Body (only if needed):**
|
||||||
|
- Skip entirely when subject is self-explanatory
|
||||||
|
- Add body only for: non-obvious *why*, breaking changes, migration notes, linked issues
|
||||||
|
- Wrap at 72 chars
|
||||||
|
- Bullets `-` not `*`
|
||||||
|
- Reference issues/PRs at end: `Closes #42`, `Refs #17`
|
||||||
|
|
||||||
|
**What NEVER goes in:**
|
||||||
|
- "This commit does X", "I", "we", "now", "currently" — the diff says what
|
||||||
|
- "As requested by..." — use Co-authored-by trailer
|
||||||
|
- "Generated with Claude Code" or any AI attribution — unless the user's own rule requires an `Assisted-by`/AI-attribution trailer, then add it as a trailer
|
||||||
|
- Emoji (unless project convention requires)
|
||||||
|
- Restating the file name when scope already says it
|
||||||
|
|
||||||
|
## Examples
|
||||||
|
|
||||||
|
Diff: new endpoint for user profile with body explaining the why
|
||||||
|
- ❌ "feat: add a new endpoint to get user profile information from the database"
|
||||||
|
- ✅
|
||||||
|
```
|
||||||
|
feat(api): add GET /users/:id/profile
|
||||||
|
|
||||||
|
Mobile client needs profile data without the full user payload
|
||||||
|
to reduce LTE bandwidth on cold-launch screens.
|
||||||
|
|
||||||
|
Closes #128
|
||||||
|
```
|
||||||
|
|
||||||
|
Diff: breaking API change
|
||||||
|
- ✅
|
||||||
|
```
|
||||||
|
feat(api)!: rename /v1/orders to /v1/checkout
|
||||||
|
|
||||||
|
BREAKING CHANGE: clients on /v1/orders must migrate to /v1/checkout
|
||||||
|
before 2026-06-01. Old route returns 410 after that date.
|
||||||
|
```
|
||||||
|
|
||||||
|
## Auto-Clarity
|
||||||
|
|
||||||
|
Always include body for: breaking changes, security fixes, data migrations, anything reverting a prior commit. Never compress these into subject-only — future debuggers need the context.
|
||||||
|
|
||||||
|
## Boundaries
|
||||||
|
|
||||||
|
Only generates the commit message. Does not run `git commit`, does not stage files, does not amend. Output the message as a code block ready to paste. "stop caveman-commit" or "normal mode": revert to verbose commit style.
|
||||||
@@ -0,0 +1,161 @@
|
|||||||
|
<p align="center">
|
||||||
|
<img src="https://em-content.zobj.net/source/apple/391/rock_1faa8.png" width="80" />
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<h1 align="center">caveman-compress</h1>
|
||||||
|
|
||||||
|
<p align="center">
|
||||||
|
<strong>shrink memory file. save token every session.</strong>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
A Claude Code skill that compresses your project memory files (`CLAUDE.md`, todos, preferences) into caveman format — so every session loads fewer tokens automatically.
|
||||||
|
|
||||||
|
Claude read `CLAUDE.md` on every session start. If file big, cost big. Caveman make file small. Cost go down forever.
|
||||||
|
|
||||||
|
## What It Do
|
||||||
|
|
||||||
|
```
|
||||||
|
/caveman-compress CLAUDE.md
|
||||||
|
```
|
||||||
|
|
||||||
|
```
|
||||||
|
CLAUDE.md ← compressed (Claude reads this — fewer tokens every session)
|
||||||
|
CLAUDE.original.md ← human-readable backup (you edit this)
|
||||||
|
```
|
||||||
|
|
||||||
|
Original never lost. You can read and edit `.original.md`. Run skill again to re-compress after edits.
|
||||||
|
|
||||||
|
## Benchmarks
|
||||||
|
|
||||||
|
Real results on real project files:
|
||||||
|
|
||||||
|
| File | Original | Compressed | Saved |
|
||||||
|
|------|----------:|----------:|------:|
|
||||||
|
| `claude-md-preferences.md` | 706 | 285 | **59.6%** |
|
||||||
|
| `project-notes.md` | 1145 | 535 | **53.3%** |
|
||||||
|
| `claude-md-project.md` | 1122 | 687 | **38.8%** |
|
||||||
|
| `todo-list.md` | 627 | 388 | **38.1%** |
|
||||||
|
| `mixed-with-code.md` | 888 | 574 | **35.4%** |
|
||||||
|
| **Average** | **898** | **494** | **45%** |
|
||||||
|
|
||||||
|
All validations passed ✅ — headings, code blocks, URLs, file paths preserved exactly.
|
||||||
|
|
||||||
|
## Before / After
|
||||||
|
|
||||||
|
<table>
|
||||||
|
<tr>
|
||||||
|
<td width="50%">
|
||||||
|
|
||||||
|
### 📄 Original (706 tokens)
|
||||||
|
|
||||||
|
> "I strongly prefer TypeScript with strict mode enabled for all new code. Please don't use `any` type unless there's genuinely no way around it, and if you do, leave a comment explaining the reasoning. I find that taking the time to properly type things catches a lot of bugs before they ever make it to runtime."
|
||||||
|
|
||||||
|
</td>
|
||||||
|
<td width="50%">
|
||||||
|
|
||||||
|
### 🪨 Caveman (285 tokens)
|
||||||
|
|
||||||
|
> "Prefer TypeScript strict mode always. No `any` unless unavoidable — comment why if used. Proper types catch bugs early."
|
||||||
|
|
||||||
|
</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
**Same instructions. 60% fewer tokens. Every. Single. Session.**
|
||||||
|
|
||||||
|
## Install
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cp -r ~/.claude/skills/caveman-compress <path-to-skill>
|
||||||
|
```
|
||||||
|
|
||||||
|
Or if you have the caveman repo:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cp -r skills/caveman-compress ~/.claude/skills/caveman-compress
|
||||||
|
```
|
||||||
|
|
||||||
|
**Requires:** Python 3.10+
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
```
|
||||||
|
/caveman-compress <filepath>
|
||||||
|
```
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
```
|
||||||
|
/caveman-compress CLAUDE.md
|
||||||
|
/caveman-compress docs/preferences.md
|
||||||
|
/caveman-compress todos.md
|
||||||
|
```
|
||||||
|
|
||||||
|
### What files work
|
||||||
|
|
||||||
|
| Type | Compress? |
|
||||||
|
|------|-----------|
|
||||||
|
| `.md`, `.txt`, `.rst` | ✅ Yes |
|
||||||
|
| Extensionless natural language | ✅ Yes |
|
||||||
|
| `.py`, `.js`, `.ts`, `.json`, `.yaml` | ❌ Skip (code/config) |
|
||||||
|
| `*.original.md` | ❌ Skip (backup files) |
|
||||||
|
|
||||||
|
## How It Work
|
||||||
|
|
||||||
|
```
|
||||||
|
/caveman-compress CLAUDE.md
|
||||||
|
↓
|
||||||
|
detect file type (no tokens)
|
||||||
|
↓
|
||||||
|
Claude compresses (tokens — one call)
|
||||||
|
↓
|
||||||
|
validate output (no tokens)
|
||||||
|
checks: headings, code blocks, URLs, file paths, bullets
|
||||||
|
↓
|
||||||
|
if errors: Claude fixes cherry-picked issues only (tokens — targeted fix)
|
||||||
|
does NOT recompress — only patches broken parts
|
||||||
|
↓
|
||||||
|
retry up to 2 times
|
||||||
|
↓
|
||||||
|
write compressed → CLAUDE.md
|
||||||
|
write original → CLAUDE.original.md
|
||||||
|
```
|
||||||
|
|
||||||
|
Only two things use tokens: initial compression + targeted fix if validation fails. Everything else is local Python.
|
||||||
|
|
||||||
|
## What Is Preserved
|
||||||
|
|
||||||
|
Caveman compress natural language. It never touch:
|
||||||
|
|
||||||
|
- Code blocks (` ``` ` fenced or indented)
|
||||||
|
- Inline code (`` `backtick content` ``)
|
||||||
|
- URLs and links
|
||||||
|
- File paths (`/src/components/...`)
|
||||||
|
- Commands (`npm install`, `git commit`)
|
||||||
|
- Technical terms, library names, API names
|
||||||
|
- Headings (exact text preserved)
|
||||||
|
- Tables (structure preserved, cell text compressed)
|
||||||
|
- Dates, version numbers, numeric values
|
||||||
|
|
||||||
|
## Why This Matter
|
||||||
|
|
||||||
|
`CLAUDE.md` loads on **every session start**. A 1000-token project memory file costs tokens every single time you open a project. Over 100 sessions that's 100,000 tokens of overhead — just for context you already wrote.
|
||||||
|
|
||||||
|
Caveman cut that by ~45% on average. Same instructions. Same accuracy. Less waste.
|
||||||
|
|
||||||
|
```
|
||||||
|
┌──────────────────────────────────────────┐
|
||||||
|
│ TOKEN SAVINGS PER FILE ████████ 45% │
|
||||||
|
│ SESSIONS THAT BENEFIT ████████ 100% │
|
||||||
|
│ INFORMATION PRESERVED ████████ 100% │
|
||||||
|
│ SETUP TIME █ 1x │
|
||||||
|
└──────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
## Part of Caveman
|
||||||
|
|
||||||
|
This skill is part of the [caveman](https://github.com/JuliusBrussee/caveman) toolkit — making Claude use fewer tokens without losing accuracy.
|
||||||
|
|
||||||
|
- **caveman** — make Claude *speak* like caveman (cuts response tokens ~65%)
|
||||||
|
- **caveman-compress** — make Claude *read* less (cuts context tokens ~45%)
|
||||||
@@ -0,0 +1,111 @@
|
|||||||
|
---
|
||||||
|
name: caveman-compress
|
||||||
|
description: >
|
||||||
|
Compress natural language memory files (CLAUDE.md, todos, preferences) into caveman format
|
||||||
|
to save input tokens. Preserves all technical substance, code, URLs, and structure.
|
||||||
|
Compressed version overwrites the original file. Human-readable backup saved as FILE.original.md.
|
||||||
|
Trigger: /caveman-compress <filepath> or "compress memory file"
|
||||||
|
---
|
||||||
|
|
||||||
|
# Caveman Compress
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
Compress natural language files (CLAUDE.md, todos, preferences) into caveman-speak to reduce input tokens. Compressed version overwrites original. Human-readable backup saved as `<filename>.original.md`.
|
||||||
|
|
||||||
|
## Trigger
|
||||||
|
|
||||||
|
`/caveman-compress <filepath>` or when user asks to compress a memory file.
|
||||||
|
|
||||||
|
## Process
|
||||||
|
|
||||||
|
1. This SKILL.md lives alongside `memory/` in the same directory. Find that directory.
|
||||||
|
|
||||||
|
2. Run:
|
||||||
|
```
|
||||||
|
cd <directory_containing_this_SKILL.md> && python3 -m scripts <absolute_filepath>
|
||||||
|
```
|
||||||
|
|
||||||
|
3. The CLI will:
|
||||||
|
- detect file type (no tokens)
|
||||||
|
- call Claude to compress
|
||||||
|
- validate output (no tokens)
|
||||||
|
- if errors: cherry-pick fix with Claude (targeted fixes only, no recompression)
|
||||||
|
- retry up to 2 times
|
||||||
|
|
||||||
|
4. Return result to user
|
||||||
|
|
||||||
|
## Compression Rules
|
||||||
|
|
||||||
|
### Remove
|
||||||
|
- Articles: a, an, the
|
||||||
|
- Filler: just, really, basically, actually, simply, essentially, generally
|
||||||
|
- Pleasantries: "sure", "certainly", "of course", "happy to", "I'd recommend"
|
||||||
|
- Hedging: "it might be worth", "you could consider", "it would be good to"
|
||||||
|
- Redundant phrasing: "in order to" → "to", "make sure to" → "ensure", "the reason is because" → "because"
|
||||||
|
- Connective fluff: "however", "furthermore", "additionally", "in addition"
|
||||||
|
|
||||||
|
### Preserve EXACTLY (never modify)
|
||||||
|
- Code blocks (fenced ``` and indented)
|
||||||
|
- Inline code (`backtick content`)
|
||||||
|
- URLs and links (full URLs, markdown links)
|
||||||
|
- File paths (`/src/components/...`, `./config.yaml`)
|
||||||
|
- Commands (`npm install`, `git commit`, `docker build`)
|
||||||
|
- Technical terms (library names, API names, protocols, algorithms)
|
||||||
|
- Proper nouns (project names, people, companies)
|
||||||
|
- Dates, version numbers, numeric values
|
||||||
|
- Environment variables (`$HOME`, `NODE_ENV`)
|
||||||
|
|
||||||
|
### Preserve Structure
|
||||||
|
- All markdown headings (keep exact heading text, compress body below)
|
||||||
|
- Bullet point hierarchy (keep nesting level)
|
||||||
|
- Numbered lists (keep numbering)
|
||||||
|
- Tables (compress cell text, keep structure)
|
||||||
|
- Frontmatter/YAML headers in markdown files
|
||||||
|
|
||||||
|
### Compress
|
||||||
|
- Use short synonyms: "big" not "extensive", "fix" not "implement a solution for", "use" not "utilize"
|
||||||
|
- Fragments OK: "Run tests before commit" not "You should always run tests before committing"
|
||||||
|
- Drop "you should", "make sure to", "remember to" — just state the action
|
||||||
|
- Merge redundant bullets that say the same thing differently
|
||||||
|
- Keep one example where multiple examples show the same pattern
|
||||||
|
|
||||||
|
CRITICAL RULE:
|
||||||
|
Anything inside ``` ... ``` must be copied EXACTLY.
|
||||||
|
Do not:
|
||||||
|
- remove comments
|
||||||
|
- remove spacing
|
||||||
|
- reorder lines
|
||||||
|
- shorten commands
|
||||||
|
- simplify anything
|
||||||
|
|
||||||
|
Inline code (`...`) must be preserved EXACTLY.
|
||||||
|
Do not modify anything inside backticks.
|
||||||
|
|
||||||
|
If file contains code blocks:
|
||||||
|
- Treat code blocks as read-only regions
|
||||||
|
- Only compress text outside them
|
||||||
|
- Do not merge sections around code
|
||||||
|
|
||||||
|
## Pattern
|
||||||
|
|
||||||
|
Original:
|
||||||
|
> You should always make sure to run the test suite before pushing any changes to the main branch. This is important because it helps catch bugs early and prevents broken builds from being deployed to production.
|
||||||
|
|
||||||
|
Compressed:
|
||||||
|
> Run tests before push to main. Catch bugs early, prevent broken prod deploys.
|
||||||
|
|
||||||
|
Original:
|
||||||
|
> The application uses a microservices architecture with the following components. The API gateway handles all incoming requests and routes them to the appropriate service. The authentication service is responsible for managing user sessions and JWT tokens.
|
||||||
|
|
||||||
|
Compressed:
|
||||||
|
> Microservices architecture. API gateway route all requests to services. Auth service manage user sessions + JWT tokens.
|
||||||
|
|
||||||
|
## Boundaries
|
||||||
|
|
||||||
|
- ONLY compress natural language files (.md, .txt, extensionless)
|
||||||
|
- NEVER modify: .py, .js, .ts, .json, .yaml, .yml, .toml, .env, .lock, .css, .html, .xml, .sql, .sh
|
||||||
|
- If file has mixed content (prose + code), compress ONLY the prose sections
|
||||||
|
- If unsure whether something is code or prose, leave it unchanged
|
||||||
|
- Original file is backed up as FILE.original.md before overwriting
|
||||||
|
- Never compress FILE.original.md (skip it)
|
||||||
@@ -0,0 +1,3 @@
|
|||||||
|
from .cli import main
|
||||||
|
|
||||||
|
main()
|
||||||
@@ -0,0 +1,78 @@
|
|||||||
|
#!/usr/bin/env python3
|
||||||
|
from pathlib import Path
|
||||||
|
import sys
|
||||||
|
|
||||||
|
# Support both direct execution and module import
|
||||||
|
try:
|
||||||
|
from .validate import validate
|
||||||
|
except ImportError:
|
||||||
|
sys.path.insert(0, str(Path(__file__).parent))
|
||||||
|
from validate import validate
|
||||||
|
|
||||||
|
try:
|
||||||
|
import tiktoken
|
||||||
|
_enc = tiktoken.get_encoding("cl100k_base")
|
||||||
|
except ImportError:
|
||||||
|
_enc = None
|
||||||
|
|
||||||
|
|
||||||
|
def count_tokens(text):
|
||||||
|
if _enc is None:
|
||||||
|
return len(text.split()) # fallback: word count
|
||||||
|
return len(_enc.encode(text))
|
||||||
|
|
||||||
|
|
||||||
|
def benchmark_pair(orig_path: Path, comp_path: Path):
|
||||||
|
orig_text = orig_path.read_text()
|
||||||
|
comp_text = comp_path.read_text()
|
||||||
|
|
||||||
|
orig_tokens = count_tokens(orig_text)
|
||||||
|
comp_tokens = count_tokens(comp_text)
|
||||||
|
saved = 100 * (orig_tokens - comp_tokens) / orig_tokens
|
||||||
|
result = validate(orig_path, comp_path)
|
||||||
|
|
||||||
|
return (comp_path.name, orig_tokens, comp_tokens, saved, result.is_valid)
|
||||||
|
|
||||||
|
|
||||||
|
def print_table(rows):
|
||||||
|
print("\n| File | Original | Compressed | Saved % | Valid |")
|
||||||
|
print("|------|----------|------------|---------|-------|")
|
||||||
|
for r in rows:
|
||||||
|
print(f"| {r[0]} | {r[1]} | {r[2]} | {r[3]:.1f}% | {'✅' if r[4] else '❌'} |")
|
||||||
|
|
||||||
|
|
||||||
|
def main():
|
||||||
|
# Direct file pair: python3 benchmark.py original.md compressed.md
|
||||||
|
if len(sys.argv) == 3:
|
||||||
|
orig = Path(sys.argv[1])
|
||||||
|
comp = Path(sys.argv[2])
|
||||||
|
if not orig.exists():
|
||||||
|
print(f"❌ Not found: {orig}")
|
||||||
|
sys.exit(1)
|
||||||
|
if not comp.exists():
|
||||||
|
print(f"❌ Not found: {comp}")
|
||||||
|
sys.exit(1)
|
||||||
|
print_table([benchmark_pair(orig, comp)])
|
||||||
|
return
|
||||||
|
|
||||||
|
# Glob mode: repo_root/tests/caveman-compress/
|
||||||
|
tests_dir = Path(__file__).parent.parent.parent / "tests" / "caveman-compress"
|
||||||
|
if not tests_dir.exists():
|
||||||
|
print(f"❌ Tests dir not found: {tests_dir}")
|
||||||
|
sys.exit(1)
|
||||||
|
|
||||||
|
rows = []
|
||||||
|
for orig in sorted(tests_dir.glob("*.original.md")):
|
||||||
|
comp = orig.with_name(orig.stem.removesuffix(".original") + ".md")
|
||||||
|
if comp.exists():
|
||||||
|
rows.append(benchmark_pair(orig, comp))
|
||||||
|
|
||||||
|
if not rows:
|
||||||
|
print("No compressed file pairs found.")
|
||||||
|
return
|
||||||
|
|
||||||
|
print_table(rows)
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
main()
|
||||||
@@ -0,0 +1,71 @@
|
|||||||
|
#!/usr/bin/env python3
|
||||||
|
"""
|
||||||
|
Caveman Memory CLI
|
||||||
|
|
||||||
|
Usage:
|
||||||
|
caveman <filepath>
|
||||||
|
"""
|
||||||
|
|
||||||
|
import sys
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
from .compress import compress_file
|
||||||
|
from .detect import detect_file_type, should_compress
|
||||||
|
|
||||||
|
|
||||||
|
def print_usage():
|
||||||
|
print("Usage: caveman <filepath>")
|
||||||
|
|
||||||
|
|
||||||
|
def main():
|
||||||
|
if len(sys.argv) != 2:
|
||||||
|
print_usage()
|
||||||
|
sys.exit(1)
|
||||||
|
|
||||||
|
filepath = Path(sys.argv[1])
|
||||||
|
|
||||||
|
# Check file exists
|
||||||
|
if not filepath.exists():
|
||||||
|
print(f"❌ File not found: {filepath}")
|
||||||
|
sys.exit(1)
|
||||||
|
|
||||||
|
if not filepath.is_file():
|
||||||
|
print(f"❌ Not a file: {filepath}")
|
||||||
|
sys.exit(1)
|
||||||
|
|
||||||
|
# Detect file type
|
||||||
|
file_type = detect_file_type(filepath)
|
||||||
|
|
||||||
|
print(f"Detected: {file_type}")
|
||||||
|
|
||||||
|
# Check if compressible
|
||||||
|
if not should_compress(filepath):
|
||||||
|
print("Skipping: file is not natural language (code/config)")
|
||||||
|
sys.exit(0)
|
||||||
|
|
||||||
|
print("Starting caveman compression...\n")
|
||||||
|
|
||||||
|
try:
|
||||||
|
success = compress_file(filepath)
|
||||||
|
|
||||||
|
if success:
|
||||||
|
print("\nCompression completed successfully")
|
||||||
|
backup_path = filepath.with_name(filepath.stem + ".original.md")
|
||||||
|
print(f"Compressed: {filepath}")
|
||||||
|
print(f"Original: {backup_path}")
|
||||||
|
sys.exit(0)
|
||||||
|
else:
|
||||||
|
print("\n❌ Compression failed after retries")
|
||||||
|
sys.exit(2)
|
||||||
|
|
||||||
|
except KeyboardInterrupt:
|
||||||
|
print("\nInterrupted by user")
|
||||||
|
sys.exit(130)
|
||||||
|
|
||||||
|
except Exception as e:
|
||||||
|
print(f"\n❌ Error: {e}")
|
||||||
|
sys.exit(1)
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
main()
|
||||||
@@ -0,0 +1,158 @@
|
|||||||
|
#!/usr/bin/env python3
|
||||||
|
"""
|
||||||
|
Caveman Memory Orchestrator
|
||||||
|
|
||||||
|
Usage:
|
||||||
|
python memory/compress.py <filepath>
|
||||||
|
"""
|
||||||
|
|
||||||
|
import subprocess
|
||||||
|
import sys
|
||||||
|
from pathlib import Path
|
||||||
|
from typing import List
|
||||||
|
|
||||||
|
from .detect import should_compress
|
||||||
|
from .validate import validate
|
||||||
|
|
||||||
|
MAX_RETRIES = 2
|
||||||
|
|
||||||
|
|
||||||
|
# ---------- Claude Calls ----------
|
||||||
|
|
||||||
|
|
||||||
|
def call_claude(prompt: str) -> str:
|
||||||
|
try:
|
||||||
|
result = subprocess.run(
|
||||||
|
["claude", "--print"],
|
||||||
|
input=prompt,
|
||||||
|
text=True,
|
||||||
|
capture_output=True,
|
||||||
|
check=True,
|
||||||
|
)
|
||||||
|
return result.stdout.strip()
|
||||||
|
except subprocess.CalledProcessError as e:
|
||||||
|
raise RuntimeError(f"Claude call failed:\n{e.stderr}")
|
||||||
|
|
||||||
|
|
||||||
|
def build_compress_prompt(original: str) -> str:
|
||||||
|
return f"""
|
||||||
|
Compress this markdown into caveman format.
|
||||||
|
|
||||||
|
STRICT RULES:
|
||||||
|
- Do NOT modify anything inside ``` code blocks
|
||||||
|
- Do NOT modify anything inside inline backticks
|
||||||
|
- Preserve ALL URLs exactly
|
||||||
|
- Preserve ALL headings exactly
|
||||||
|
- Preserve file paths and commands
|
||||||
|
|
||||||
|
Only compress natural language.
|
||||||
|
|
||||||
|
TEXT:
|
||||||
|
{original}
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
def build_fix_prompt(original: str, compressed: str, errors: List[str]) -> str:
|
||||||
|
errors_str = "\n".join(f"- {e}" for e in errors)
|
||||||
|
return f"""You are fixing a caveman-compressed markdown file. Specific validation errors were found.
|
||||||
|
|
||||||
|
CRITICAL RULES:
|
||||||
|
- DO NOT recompress or rephrase the file
|
||||||
|
- ONLY fix the listed errors — leave everything else exactly as-is
|
||||||
|
- The ORIGINAL is provided as reference only (to restore missing content)
|
||||||
|
- Preserve caveman style in all untouched sections
|
||||||
|
|
||||||
|
ERRORS TO FIX:
|
||||||
|
{errors_str}
|
||||||
|
|
||||||
|
HOW TO FIX:
|
||||||
|
- Missing URL: find it in ORIGINAL, restore it exactly where it belongs in COMPRESSED
|
||||||
|
- Code block mismatch: find the exact code block in ORIGINAL, restore it in COMPRESSED
|
||||||
|
- Heading mismatch: restore the exact heading text from ORIGINAL into COMPRESSED
|
||||||
|
- Do not touch any section not mentioned in the errors
|
||||||
|
|
||||||
|
ORIGINAL (reference only):
|
||||||
|
{original}
|
||||||
|
|
||||||
|
COMPRESSED (fix this):
|
||||||
|
{compressed}
|
||||||
|
|
||||||
|
Return ONLY the fixed compressed file. No explanation.
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
# ---------- Core Logic ----------
|
||||||
|
|
||||||
|
|
||||||
|
def compress_file(filepath: Path) -> bool:
|
||||||
|
print(f"📄 Processing: {filepath}")
|
||||||
|
|
||||||
|
if not should_compress(filepath):
|
||||||
|
print("⚠️ Skipping (not natural language)")
|
||||||
|
return False
|
||||||
|
|
||||||
|
original_text = filepath.read_text(errors="ignore")
|
||||||
|
backup_path = filepath.with_name(filepath.stem + ".original.md")
|
||||||
|
|
||||||
|
# Step 1: Compress
|
||||||
|
print("🧠 Compressing with Claude...")
|
||||||
|
compressed = call_claude(build_compress_prompt(original_text))
|
||||||
|
|
||||||
|
# Save original as backup, write compressed to original path
|
||||||
|
backup_path.write_text(original_text)
|
||||||
|
filepath.write_text(compressed)
|
||||||
|
|
||||||
|
# Step 2: Validate + Retry
|
||||||
|
for attempt in range(MAX_RETRIES):
|
||||||
|
print(f"\n🔍 Validation attempt {attempt + 1}")
|
||||||
|
|
||||||
|
result = validate(backup_path, filepath)
|
||||||
|
|
||||||
|
if result.is_valid:
|
||||||
|
print("✅ Validation passed")
|
||||||
|
break
|
||||||
|
|
||||||
|
print("❌ Validation failed:")
|
||||||
|
for err in result.errors:
|
||||||
|
print(f" - {err}")
|
||||||
|
|
||||||
|
if attempt == MAX_RETRIES - 1:
|
||||||
|
# Restore original on failure
|
||||||
|
filepath.write_text(original_text)
|
||||||
|
backup_path.unlink(missing_ok=True)
|
||||||
|
print("❌ Failed after retries — original restored")
|
||||||
|
return False
|
||||||
|
|
||||||
|
print("🛠 Fixing with Claude...")
|
||||||
|
compressed = call_claude(
|
||||||
|
build_fix_prompt(original_text, compressed, result.errors)
|
||||||
|
)
|
||||||
|
filepath.write_text(compressed)
|
||||||
|
|
||||||
|
return True
|
||||||
|
|
||||||
|
|
||||||
|
# ---------- Main ----------
|
||||||
|
|
||||||
|
|
||||||
|
def main():
|
||||||
|
if len(sys.argv) != 2:
|
||||||
|
print("Usage: python memory/compress.py <filepath>")
|
||||||
|
sys.exit(1)
|
||||||
|
|
||||||
|
filepath = Path(sys.argv[1])
|
||||||
|
|
||||||
|
if not filepath.exists():
|
||||||
|
print(f"❌ File not found: {filepath}")
|
||||||
|
sys.exit(1)
|
||||||
|
|
||||||
|
success = compress_file(filepath)
|
||||||
|
|
||||||
|
if success:
|
||||||
|
sys.exit(0)
|
||||||
|
else:
|
||||||
|
sys.exit(2)
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
main()
|
||||||
@@ -0,0 +1,121 @@
|
|||||||
|
#!/usr/bin/env python3
|
||||||
|
"""Detect whether a file is natural language (compressible) or code/config (skip)."""
|
||||||
|
|
||||||
|
import json
|
||||||
|
import re
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
# Extensions that are natural language and compressible
|
||||||
|
COMPRESSIBLE_EXTENSIONS = {".md", ".txt", ".markdown", ".rst"}
|
||||||
|
|
||||||
|
# Extensions that are code/config and should be skipped
|
||||||
|
SKIP_EXTENSIONS = {
|
||||||
|
".py", ".js", ".ts", ".tsx", ".jsx", ".json", ".yaml", ".yml",
|
||||||
|
".toml", ".env", ".lock", ".css", ".scss", ".html", ".xml",
|
||||||
|
".sql", ".sh", ".bash", ".zsh", ".go", ".rs", ".java", ".c",
|
||||||
|
".cpp", ".h", ".hpp", ".rb", ".php", ".swift", ".kt", ".lua",
|
||||||
|
".dockerfile", ".makefile", ".csv", ".ini", ".cfg",
|
||||||
|
}
|
||||||
|
|
||||||
|
# Patterns that indicate a line is code
|
||||||
|
CODE_PATTERNS = [
|
||||||
|
re.compile(r"^\s*(import |from .+ import |require\(|const |let |var )"),
|
||||||
|
re.compile(r"^\s*(def |class |function |async function |export )"),
|
||||||
|
re.compile(r"^\s*(if\s*\(|for\s*\(|while\s*\(|switch\s*\(|try\s*\{)"),
|
||||||
|
re.compile(r"^\s*[\}\]\);]+\s*$"), # closing braces/brackets
|
||||||
|
re.compile(r"^\s*@\w+"), # decorators/annotations
|
||||||
|
re.compile(r'^\s*"[^"]+"\s*:\s*'), # JSON-like key-value
|
||||||
|
re.compile(r"^\s*\w+\s*=\s*[{\[\(\"']"), # assignment with literal
|
||||||
|
]
|
||||||
|
|
||||||
|
|
||||||
|
def _is_code_line(line: str) -> bool:
|
||||||
|
"""Check if a line looks like code."""
|
||||||
|
return any(p.match(line) for p in CODE_PATTERNS)
|
||||||
|
|
||||||
|
|
||||||
|
def _is_json_content(text: str) -> bool:
|
||||||
|
"""Check if content is valid JSON."""
|
||||||
|
try:
|
||||||
|
json.loads(text)
|
||||||
|
return True
|
||||||
|
except (json.JSONDecodeError, ValueError):
|
||||||
|
return False
|
||||||
|
|
||||||
|
|
||||||
|
def _is_yaml_content(lines: list[str]) -> bool:
|
||||||
|
"""Heuristic: check if content looks like YAML."""
|
||||||
|
yaml_indicators = 0
|
||||||
|
for line in lines[:30]:
|
||||||
|
stripped = line.strip()
|
||||||
|
if stripped.startswith("---"):
|
||||||
|
yaml_indicators += 1
|
||||||
|
elif re.match(r"^\w[\w\s]*:\s", stripped):
|
||||||
|
yaml_indicators += 1
|
||||||
|
elif stripped.startswith("- ") and ":" in stripped:
|
||||||
|
yaml_indicators += 1
|
||||||
|
# If most non-empty lines look like YAML
|
||||||
|
non_empty = sum(1 for l in lines[:30] if l.strip())
|
||||||
|
return non_empty > 0 and yaml_indicators / non_empty > 0.6
|
||||||
|
|
||||||
|
|
||||||
|
def detect_file_type(filepath: Path) -> str:
|
||||||
|
"""Classify a file as 'natural_language', 'code', 'config', or 'unknown'.
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
One of: 'natural_language', 'code', 'config', 'unknown'
|
||||||
|
"""
|
||||||
|
ext = filepath.suffix.lower()
|
||||||
|
|
||||||
|
# Extension-based classification
|
||||||
|
if ext in COMPRESSIBLE_EXTENSIONS:
|
||||||
|
return "natural_language"
|
||||||
|
if ext in SKIP_EXTENSIONS:
|
||||||
|
return "code" if ext not in {".json", ".yaml", ".yml", ".toml", ".ini", ".cfg", ".env"} else "config"
|
||||||
|
|
||||||
|
# Extensionless files (like CLAUDE.md, TODO) — check content
|
||||||
|
if not ext:
|
||||||
|
try:
|
||||||
|
text = filepath.read_text(errors="ignore")
|
||||||
|
except (OSError, PermissionError):
|
||||||
|
return "unknown"
|
||||||
|
|
||||||
|
lines = text.splitlines()[:50]
|
||||||
|
|
||||||
|
if _is_json_content(text[:10000]):
|
||||||
|
return "config"
|
||||||
|
if _is_yaml_content(lines):
|
||||||
|
return "config"
|
||||||
|
|
||||||
|
code_lines = sum(1 for l in lines if l.strip() and _is_code_line(l))
|
||||||
|
non_empty = sum(1 for l in lines if l.strip())
|
||||||
|
if non_empty > 0 and code_lines / non_empty > 0.4:
|
||||||
|
return "code"
|
||||||
|
|
||||||
|
return "natural_language"
|
||||||
|
|
||||||
|
return "unknown"
|
||||||
|
|
||||||
|
|
||||||
|
def should_compress(filepath: Path) -> bool:
|
||||||
|
"""Return True if the file is natural language and should be compressed."""
|
||||||
|
if not filepath.is_file():
|
||||||
|
return False
|
||||||
|
# Skip backup files
|
||||||
|
if filepath.name.endswith(".original.md"):
|
||||||
|
return False
|
||||||
|
return detect_file_type(filepath) == "natural_language"
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
import sys
|
||||||
|
|
||||||
|
if len(sys.argv) < 2:
|
||||||
|
print("Usage: python detect.py <file1> [file2] ...")
|
||||||
|
sys.exit(1)
|
||||||
|
|
||||||
|
for path_str in sys.argv[1:]:
|
||||||
|
p = Path(path_str)
|
||||||
|
file_type = detect_file_type(p)
|
||||||
|
compress = should_compress(p)
|
||||||
|
print(f" {p.name:30s} type={file_type:20s} compress={compress}")
|
||||||
@@ -0,0 +1,148 @@
|
|||||||
|
#!/usr/bin/env python3
|
||||||
|
import re
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
URL_REGEX = re.compile(r"https?://[^\s)]+")
|
||||||
|
CODE_BLOCK_REGEX = re.compile(r"```.*?```", re.DOTALL)
|
||||||
|
HEADING_REGEX = re.compile(r"^(#{1,6})\s+(.*)", re.MULTILINE)
|
||||||
|
BULLET_REGEX = re.compile(r"^\s*[-*+]\s+", re.MULTILINE)
|
||||||
|
|
||||||
|
# crude but effective path detection
|
||||||
|
PATH_REGEX = re.compile(r"(\./|\../|/|[A-Za-z]:\\)[\w\-/\\\.]+")
|
||||||
|
|
||||||
|
|
||||||
|
class ValidationResult:
|
||||||
|
def __init__(self):
|
||||||
|
self.is_valid = True
|
||||||
|
self.errors = []
|
||||||
|
self.warnings = []
|
||||||
|
|
||||||
|
def add_error(self, msg):
|
||||||
|
self.is_valid = False
|
||||||
|
self.errors.append(msg)
|
||||||
|
|
||||||
|
def add_warning(self, msg):
|
||||||
|
self.warnings.append(msg)
|
||||||
|
|
||||||
|
|
||||||
|
def read_file(path: Path) -> str:
|
||||||
|
return path.read_text(errors="ignore")
|
||||||
|
|
||||||
|
|
||||||
|
# ---------- Extractors ----------
|
||||||
|
|
||||||
|
|
||||||
|
def extract_headings(text):
|
||||||
|
return [(level, title.strip()) for level, title in HEADING_REGEX.findall(text)]
|
||||||
|
|
||||||
|
|
||||||
|
def extract_code_blocks(text):
|
||||||
|
return CODE_BLOCK_REGEX.findall(text)
|
||||||
|
|
||||||
|
|
||||||
|
def extract_urls(text):
|
||||||
|
return set(URL_REGEX.findall(text))
|
||||||
|
|
||||||
|
|
||||||
|
def extract_paths(text):
|
||||||
|
return set(PATH_REGEX.findall(text))
|
||||||
|
|
||||||
|
|
||||||
|
def count_bullets(text):
|
||||||
|
return len(BULLET_REGEX.findall(text))
|
||||||
|
|
||||||
|
|
||||||
|
# ---------- Validators ----------
|
||||||
|
|
||||||
|
|
||||||
|
def validate_headings(orig, comp, result):
|
||||||
|
h1 = extract_headings(orig)
|
||||||
|
h2 = extract_headings(comp)
|
||||||
|
|
||||||
|
if len(h1) != len(h2):
|
||||||
|
result.add_error(f"Heading count mismatch: {len(h1)} vs {len(h2)}")
|
||||||
|
|
||||||
|
if h1 != h2:
|
||||||
|
result.add_warning("Heading text/order changed")
|
||||||
|
|
||||||
|
|
||||||
|
def validate_code_blocks(orig, comp, result):
|
||||||
|
c1 = extract_code_blocks(orig)
|
||||||
|
c2 = extract_code_blocks(comp)
|
||||||
|
|
||||||
|
if c1 != c2:
|
||||||
|
result.add_error("Code blocks not preserved exactly")
|
||||||
|
|
||||||
|
|
||||||
|
def validate_urls(orig, comp, result):
|
||||||
|
u1 = extract_urls(orig)
|
||||||
|
u2 = extract_urls(comp)
|
||||||
|
|
||||||
|
if u1 != u2:
|
||||||
|
result.add_error(f"URL mismatch: lost={u1 - u2}, added={u2 - u1}")
|
||||||
|
|
||||||
|
|
||||||
|
def validate_paths(orig, comp, result):
|
||||||
|
p1 = extract_paths(orig)
|
||||||
|
p2 = extract_paths(comp)
|
||||||
|
|
||||||
|
if p1 != p2:
|
||||||
|
result.add_warning(f"Path mismatch: lost={p1 - p2}, added={p2 - p1}")
|
||||||
|
|
||||||
|
|
||||||
|
def validate_bullets(orig, comp, result):
|
||||||
|
b1 = count_bullets(orig)
|
||||||
|
b2 = count_bullets(comp)
|
||||||
|
|
||||||
|
if b1 == 0:
|
||||||
|
return
|
||||||
|
|
||||||
|
diff = abs(b1 - b2) / b1
|
||||||
|
|
||||||
|
if diff > 0.15:
|
||||||
|
result.add_warning(f"Bullet count changed too much: {b1} -> {b2}")
|
||||||
|
|
||||||
|
|
||||||
|
# ---------- Main ----------
|
||||||
|
|
||||||
|
|
||||||
|
def validate(original_path: Path, compressed_path: Path) -> ValidationResult:
|
||||||
|
result = ValidationResult()
|
||||||
|
|
||||||
|
orig = read_file(original_path)
|
||||||
|
comp = read_file(compressed_path)
|
||||||
|
|
||||||
|
validate_headings(orig, comp, result)
|
||||||
|
validate_code_blocks(orig, comp, result)
|
||||||
|
validate_urls(orig, comp, result)
|
||||||
|
validate_paths(orig, comp, result)
|
||||||
|
validate_bullets(orig, comp, result)
|
||||||
|
|
||||||
|
return result
|
||||||
|
|
||||||
|
|
||||||
|
# ---------- CLI ----------
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
import sys
|
||||||
|
|
||||||
|
if len(sys.argv) != 3:
|
||||||
|
print("Usage: python validate.py <original> <compressed>")
|
||||||
|
sys.exit(1)
|
||||||
|
|
||||||
|
orig = Path(sys.argv[1])
|
||||||
|
comp = Path(sys.argv[2])
|
||||||
|
|
||||||
|
res = validate(orig, comp)
|
||||||
|
|
||||||
|
print(f"\nValid: {res.is_valid}")
|
||||||
|
|
||||||
|
if res.errors:
|
||||||
|
print("\nErrors:")
|
||||||
|
for e in res.errors:
|
||||||
|
print(f" - {e}")
|
||||||
|
|
||||||
|
if res.warnings:
|
||||||
|
print("\nWarnings:")
|
||||||
|
for w in res.warnings:
|
||||||
|
print(f" - {w}")
|
||||||
@@ -0,0 +1,67 @@
|
|||||||
|
---
|
||||||
|
name: caveman
|
||||||
|
description: >
|
||||||
|
Ultra-compressed communication mode. Cuts token usage ~75% by speaking like caveman
|
||||||
|
while keeping full technical accuracy. Supports intensity levels: lite, full (default), ultra,
|
||||||
|
wenyan-lite, wenyan-full, wenyan-ultra.
|
||||||
|
Use when user says "caveman mode", "talk like caveman", "use caveman", "less tokens",
|
||||||
|
"be brief", or invokes /caveman. Also auto-triggers when token efficiency is requested.
|
||||||
|
---
|
||||||
|
|
||||||
|
Respond terse like smart caveman. All technical substance stay. Only fluff die.
|
||||||
|
|
||||||
|
## Persistence
|
||||||
|
|
||||||
|
ACTIVE EVERY RESPONSE. No revert after many turns. No filler drift. Still active if unsure. Off only: "stop caveman" / "normal mode".
|
||||||
|
|
||||||
|
Default: **full**. Switch: `/caveman lite|full|ultra`.
|
||||||
|
|
||||||
|
## Rules
|
||||||
|
|
||||||
|
Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). Technical terms exact. Code blocks unchanged. Errors quoted exact.
|
||||||
|
|
||||||
|
Pattern: `[thing] [action] [reason]. [next step].`
|
||||||
|
|
||||||
|
Not: "Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by..."
|
||||||
|
Yes: "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"
|
||||||
|
|
||||||
|
## Intensity
|
||||||
|
|
||||||
|
| Level | What change |
|
||||||
|
|-------|------------|
|
||||||
|
| **lite** | No filler/hedging. Keep articles + full sentences. Professional but tight |
|
||||||
|
| **full** | Drop articles, fragments OK, short synonyms. Classic caveman |
|
||||||
|
| **ultra** | Abbreviate (DB/auth/config/req/res/fn/impl), strip conjunctions, arrows for causality (X → Y), one word when one word enough |
|
||||||
|
| **wenyan-lite** | Semi-classical. Drop filler/hedging but keep grammar structure, classical register |
|
||||||
|
| **wenyan-full** | Maximum classical terseness. Fully 文言文. 80-90% character reduction. Classical sentence patterns, verbs precede objects, subjects often omitted, classical particles (之/乃/為/其) |
|
||||||
|
| **wenyan-ultra** | Extreme abbreviation while keeping classical Chinese feel. Maximum compression, ultra terse |
|
||||||
|
|
||||||
|
Example — "Why React component re-render?"
|
||||||
|
- lite: "Your component re-renders because you create a new object reference each render. Wrap it in `useMemo`."
|
||||||
|
- full: "New object ref each render. Inline object prop = new ref = re-render. Wrap in `useMemo`."
|
||||||
|
- ultra: "Inline obj prop → new ref → re-render. `useMemo`."
|
||||||
|
- wenyan-lite: "組件頻重繪,以每繪新生對象參照故。以 useMemo 包之。"
|
||||||
|
- wenyan-full: "物出新參照,致重繪。useMemo .Wrap之。"
|
||||||
|
- wenyan-ultra: "新參照→重繪。useMemo Wrap。"
|
||||||
|
|
||||||
|
Example — "Explain database connection pooling."
|
||||||
|
- lite: "Connection pooling reuses open connections instead of creating new ones per request. Avoids repeated handshake overhead."
|
||||||
|
- full: "Pool reuse open DB connections. No new connection per request. Skip handshake overhead."
|
||||||
|
- ultra: "Pool = reuse DB conn. Skip handshake → fast under load."
|
||||||
|
- wenyan-full: "池reuse open connection。不每req新開。skip handshake overhead。"
|
||||||
|
- wenyan-ultra: "池reuse conn。skip handshake → fast。"
|
||||||
|
|
||||||
|
## Auto-Clarity
|
||||||
|
|
||||||
|
Drop caveman for: security warnings, irreversible action confirmations, multi-step sequences where fragment order risks misread, user asks to clarify or repeats question. Resume caveman after clear part done.
|
||||||
|
|
||||||
|
Example — destructive op:
|
||||||
|
> **Warning:** This will permanently delete all rows in the `users` table and cannot be undone.
|
||||||
|
> ```sql
|
||||||
|
> DROP TABLE users;
|
||||||
|
> ```
|
||||||
|
> Caveman resume. Verify backup exist first.
|
||||||
|
|
||||||
|
## Boundaries
|
||||||
|
|
||||||
|
Code/commits/PRs: write normal. "stop caveman" or "normal mode": revert. Level persist until changed or session end.
|
||||||
@@ -0,0 +1,141 @@
|
|||||||
|
---
|
||||||
|
name: find-skills
|
||||||
|
description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Find Skills
|
||||||
|
|
||||||
|
This skill helps you discover and install skills from the open agent skills ecosystem.
|
||||||
|
|
||||||
|
## When to Use This Skill
|
||||||
|
|
||||||
|
Use this skill when the user:
|
||||||
|
|
||||||
|
- Asks "how do I do X" where X might be a common task with an existing skill
|
||||||
|
- Says "find a skill for X" or "is there a skill for X"
|
||||||
|
- Asks "can you do X" where X is a specialized capability
|
||||||
|
- Expresses interest in extending agent capabilities
|
||||||
|
- Wants to search for tools, templates, or workflows
|
||||||
|
- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
|
||||||
|
|
||||||
|
## What is the Skills CLI?
|
||||||
|
|
||||||
|
The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
|
||||||
|
|
||||||
|
**Key commands:**
|
||||||
|
|
||||||
|
- `npx skills find [query] [--owner <owner>]` - Search for skills interactively or by keyword, optionally scoped to a GitHub owner
|
||||||
|
- `npx skills add <package>` - Install a skill from GitHub or other sources
|
||||||
|
- `npx skills update` - Update all installed skills
|
||||||
|
|
||||||
|
**Browse skills at:** https://skills.sh/
|
||||||
|
|
||||||
|
## How to Help Users Find Skills
|
||||||
|
|
||||||
|
### Step 1: Understand What They Need
|
||||||
|
|
||||||
|
When a user asks for help with something, identify:
|
||||||
|
|
||||||
|
1. The domain (e.g., React, testing, design, deployment)
|
||||||
|
2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
|
||||||
|
3. Whether this is a common enough task that a skill likely exists
|
||||||
|
|
||||||
|
### Step 2: Check the Leaderboard First
|
||||||
|
|
||||||
|
Before running a CLI search, check the [skills.sh leaderboard](https://skills.sh/) to see if a well-known skill already exists for the domain. The leaderboard ranks skills by total installs, surfacing the most popular and battle-tested options.
|
||||||
|
|
||||||
|
For example, top skills for web development include:
|
||||||
|
- `vercel-labs/agent-skills` — React, Next.js, web design (100K+ installs each)
|
||||||
|
- `anthropics/skills` — Frontend design, document processing (100K+ installs)
|
||||||
|
|
||||||
|
### Step 3: Search for Skills
|
||||||
|
|
||||||
|
If the leaderboard doesn't cover the user's need, run the find command:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx skills find [query] [--owner <owner>]
|
||||||
|
```
|
||||||
|
|
||||||
|
For example:
|
||||||
|
|
||||||
|
- User asks "how do I make my React app faster?" → `npx skills find react performance`
|
||||||
|
- User asks "can you help me with PR reviews?" → `npx skills find pr review`
|
||||||
|
- User asks "I need to create a changelog" → `npx skills find changelog`
|
||||||
|
|
||||||
|
### Step 4: Verify Quality Before Recommending
|
||||||
|
|
||||||
|
**Do not recommend a skill based solely on search results.** Always verify:
|
||||||
|
|
||||||
|
1. **Install count** — Prefer skills with 1K+ installs. Be cautious with anything under 100.
|
||||||
|
2. **Source reputation** — Official sources (`vercel-labs`, `anthropics`, `microsoft`) are more trustworthy than unknown authors.
|
||||||
|
3. **GitHub stars** — Check the source repository. A skill from a repo with <100 stars should be treated with skepticism.
|
||||||
|
|
||||||
|
### Step 5: Present Options to the User
|
||||||
|
|
||||||
|
When you find relevant skills, present them to the user with:
|
||||||
|
|
||||||
|
1. The skill name and what it does
|
||||||
|
2. The install count and source
|
||||||
|
3. The install command they can run
|
||||||
|
4. A link to learn more at skills.sh
|
||||||
|
|
||||||
|
Example response:
|
||||||
|
|
||||||
|
```
|
||||||
|
I found a skill that might help! The "react-best-practices" skill provides
|
||||||
|
React and Next.js performance optimization guidelines from Vercel Engineering.
|
||||||
|
(185K installs)
|
||||||
|
|
||||||
|
To install it:
|
||||||
|
npx skills add vercel-labs/agent-skills@react-best-practices
|
||||||
|
|
||||||
|
Learn more: https://skills.sh/vercel-labs/agent-skills/react-best-practices
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 6: Offer to Install
|
||||||
|
|
||||||
|
If the user wants to proceed, you can install the skill for them:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx skills add <owner/repo@skill> -g -y
|
||||||
|
```
|
||||||
|
|
||||||
|
The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
|
||||||
|
|
||||||
|
## Common Skill Categories
|
||||||
|
|
||||||
|
When searching, consider these common categories:
|
||||||
|
|
||||||
|
| Category | Example Queries |
|
||||||
|
| --------------- | ---------------------------------------- |
|
||||||
|
| Web Development | react, nextjs, typescript, css, tailwind |
|
||||||
|
| Testing | testing, jest, playwright, e2e |
|
||||||
|
| DevOps | deploy, docker, kubernetes, ci-cd |
|
||||||
|
| Documentation | docs, readme, changelog, api-docs |
|
||||||
|
| Code Quality | review, lint, refactor, best-practices |
|
||||||
|
| Design | ui, ux, design-system, accessibility |
|
||||||
|
| Productivity | workflow, automation, git |
|
||||||
|
|
||||||
|
## Tips for Effective Searches
|
||||||
|
|
||||||
|
1. **Use specific keywords**: "react testing" is better than just "testing"
|
||||||
|
2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
|
||||||
|
3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
|
||||||
|
|
||||||
|
## When No Skills Are Found
|
||||||
|
|
||||||
|
If no relevant skills exist:
|
||||||
|
|
||||||
|
1. Acknowledge that no existing skill was found
|
||||||
|
2. Offer to help with the task directly using your general capabilities
|
||||||
|
3. Suggest the user could create their own skill with `npx skills init`
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```
|
||||||
|
I searched for skills related to "xyz" but didn't find any matches.
|
||||||
|
I can still help you with this task directly! Would you like me to proceed?
|
||||||
|
|
||||||
|
If this is something you do often, you could create your own skill:
|
||||||
|
npx skills init my-xyz-skill
|
||||||
|
```
|
||||||
@@ -0,0 +1,67 @@
|
|||||||
|
---
|
||||||
|
name: karpathy-guidelines
|
||||||
|
description: Behavioral guidelines to reduce common LLM coding mistakes. Use when writing, reviewing, or refactoring code to avoid overcomplication, make surgical changes, surface assumptions, and define verifiable success criteria.
|
||||||
|
license: MIT
|
||||||
|
---
|
||||||
|
|
||||||
|
# Karpathy Guidelines
|
||||||
|
|
||||||
|
Behavioral guidelines to reduce common LLM coding mistakes, derived from [Andrej Karpathy's observations](https://x.com/karpathy/status/2015883857489522876) on LLM coding pitfalls.
|
||||||
|
|
||||||
|
**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
|
||||||
|
|
||||||
|
## 1. Think Before Coding
|
||||||
|
|
||||||
|
**Don't assume. Don't hide confusion. Surface tradeoffs.**
|
||||||
|
|
||||||
|
Before implementing:
|
||||||
|
- State your assumptions explicitly. If uncertain, ask.
|
||||||
|
- If multiple interpretations exist, present them - don't pick silently.
|
||||||
|
- If a simpler approach exists, say so. Push back when warranted.
|
||||||
|
- If something is unclear, stop. Name what's confusing. Ask.
|
||||||
|
|
||||||
|
## 2. Simplicity First
|
||||||
|
|
||||||
|
**Minimum code that solves the problem. Nothing speculative.**
|
||||||
|
|
||||||
|
- No features beyond what was asked.
|
||||||
|
- No abstractions for single-use code.
|
||||||
|
- No "flexibility" or "configurability" that wasn't requested.
|
||||||
|
- No error handling for impossible scenarios.
|
||||||
|
- If you write 200 lines and it could be 50, rewrite it.
|
||||||
|
|
||||||
|
Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
|
||||||
|
|
||||||
|
## 3. Surgical Changes
|
||||||
|
|
||||||
|
**Touch only what you must. Clean up only your own mess.**
|
||||||
|
|
||||||
|
When editing existing code:
|
||||||
|
- Don't "improve" adjacent code, comments, or formatting.
|
||||||
|
- Don't refactor things that aren't broken.
|
||||||
|
- Match existing style, even if you'd do it differently.
|
||||||
|
- If you notice unrelated dead code, mention it - don't delete it.
|
||||||
|
|
||||||
|
When your changes create orphans:
|
||||||
|
- Remove imports/variables/functions that YOUR changes made unused.
|
||||||
|
- Don't remove pre-existing dead code unless asked.
|
||||||
|
|
||||||
|
The test: Every changed line should trace directly to the user's request.
|
||||||
|
|
||||||
|
## 4. Goal-Driven Execution
|
||||||
|
|
||||||
|
**Define success criteria. Loop until verified.**
|
||||||
|
|
||||||
|
Transform tasks into verifiable goals:
|
||||||
|
- "Add validation" → "Write tests for invalid inputs, then make them pass"
|
||||||
|
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
|
||||||
|
- "Refactor X" → "Ensure tests pass before and after"
|
||||||
|
|
||||||
|
For multi-step tasks, state a brief plan:
|
||||||
|
```
|
||||||
|
1. [Step] → verify: [check]
|
||||||
|
2. [Step] → verify: [check]
|
||||||
|
3. [Step] → verify: [check]
|
||||||
|
```
|
||||||
|
|
||||||
|
Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
|
||||||
@@ -0,0 +1,103 @@
|
|||||||
|
---
|
||||||
|
name: ponytail-audit
|
||||||
|
description: >
|
||||||
|
Quality audit of a whole repo: bugs, security holes, what breaks under real
|
||||||
|
load, risky code without tests, slow paths, and what to delete, merge or
|
||||||
|
split. Ranked, each finding explained in plain English. One-shot report,
|
||||||
|
changes nothing. Use for "audit this codebase", "review the whole repo",
|
||||||
|
"find bloat", "what can I delete", /ponytail-audit.
|
||||||
|
---
|
||||||
|
|
||||||
|
Audit the whole repo like the senior developer who just inherited it and
|
||||||
|
will be paged when it breaks. Order of importance: correct, safe, holds under
|
||||||
|
load, tested, fast, lean. Lean still matters: every extra line must be read,
|
||||||
|
tested and fixed later. This is a report the user asked for, so give it in full.
|
||||||
|
|
||||||
|
## 1. Map first
|
||||||
|
|
||||||
|
- Audit what the user names: a folder, a package, or the whole repo.
|
||||||
|
Nothing named: the whole repo.
|
||||||
|
- Read the README, the deploy and build config, the dependency list, the
|
||||||
|
entry points (main, routes, handlers, jobs, CLI commands) and the tests.
|
||||||
|
- Find the expected load: one person running a script, or many users and
|
||||||
|
processes at once. Judge scale against that, and say which load you assumed.
|
||||||
|
- Trace the main flows end to end: where data comes in, what is stored,
|
||||||
|
what goes out. Read those paths fully: input from users, money, auth,
|
||||||
|
data writes, background jobs, anything shared between processes.
|
||||||
|
- Big repo: go deep where a mistake costs the most, not file by file. Say
|
||||||
|
which parts you did not read.
|
||||||
|
|
||||||
|
## 2. Look for
|
||||||
|
|
||||||
|
1. **Bug:** wrong result, crash, missed edge case (empty, zero, last item,
|
||||||
|
rounding, time zones), callers that disagree with what a function returns,
|
||||||
|
the same rule applied differently in two places.
|
||||||
|
2. **Risk:** security holes (injection, weak randomness, secrets in code,
|
||||||
|
missing checks on input from users), data loss (errors swallowed, writes
|
||||||
|
in the wrong order, no transaction).
|
||||||
|
3. **Scale:** fine for one user, wrong for many: check-then-write races, the
|
||||||
|
same work done by every process, memory or lists that only grow, a query
|
||||||
|
per item, O(n^2) on big input, per-process state that must be shared.
|
||||||
|
4. **Missing test:** risky logic (a branch, a parser, money, security, data
|
||||||
|
writes) with no test that fails when it breaks. One good test, not coverage.
|
||||||
|
5. **Speed:** big slowdowns are problems. Small wins (work repeated in a hot
|
||||||
|
loop) are suggestions; some software counts every millisecond.
|
||||||
|
6. **Lean:** code that should not exist or should be smaller.
|
||||||
|
- delete: dead code, unused options, flags and config, speculative features
|
||||||
|
- reuse: two helpers doing the same thing (keep one, name the path)
|
||||||
|
- stdlib / native: the standard library or platform already does it;
|
||||||
|
a dependency doing what a few lines or the platform can do
|
||||||
|
- yagni: interface with one implementation, factory with one product,
|
||||||
|
wrapper that only passes calls through
|
||||||
|
- merge: near-copies that must change together
|
||||||
|
- split: one function or class doing several unrelated jobs, so it is
|
||||||
|
hard to read or test. Split by job, never by line count, and never into
|
||||||
|
helpers that exist only to make a function shorter.
|
||||||
|
|
||||||
|
## 3. Check before you report
|
||||||
|
|
||||||
|
- Every finding needs a concrete case: "this input or situation leads to this
|
||||||
|
wrong result". No case, no finding.
|
||||||
|
- Before calling code unused, grep the whole tree for it, including tests,
|
||||||
|
fixtures, config, and string or dynamic references.
|
||||||
|
- A shortcut marked with a `shortcut:` (or older `ponytail:`) comment that names its limit is a
|
||||||
|
decision, not a finding, unless the expected load already crosses it.
|
||||||
|
- Propose the smallest fix that works. Prefer fixes that delete code. Never
|
||||||
|
add layers, frameworks or config the problem does not need.
|
||||||
|
- No style taste, no "consider", no vague worries.
|
||||||
|
|
||||||
|
## 4. Output
|
||||||
|
|
||||||
|
Very simple English: short sentences, everyday words. Explain a technical
|
||||||
|
term the first time you use it. The reader may never have seen this code.
|
||||||
|
|
||||||
|
Start with `What this repo does:` in two or three sentences, and the load
|
||||||
|
you assumed.
|
||||||
|
|
||||||
|
Then the findings in three groups, most important first, skip empty groups:
|
||||||
|
- **Must fix:** bug, security, data loss, breaks at the expected load.
|
||||||
|
- **Should fix:** risky code without a test, real slowness, duplication, a
|
||||||
|
function that mixes jobs, code that should not exist.
|
||||||
|
- **Nice to have:** small speed-ups, shorter forms.
|
||||||
|
|
||||||
|
Number findings across all groups, so the user can say "fix 2 and 5". At
|
||||||
|
most 20 findings; if you left smaller ones out, say how many.
|
||||||
|
Every finding has all four parts, each one or two short sentences:
|
||||||
|
|
||||||
|
2. **Orders land on the wrong day** (`billing/close_day.py:L40-52`)
|
||||||
|
- **What this is:** At midnight this job closes the day and bills all orders of that day.
|
||||||
|
- **Problem:** It takes "today" from the server clock, which runs in UTC. An order placed
|
||||||
|
at 00:30 in Berlin is billed on the day before.
|
||||||
|
- **Fix:** Compute the day once in the shop's time zone:
|
||||||
|
`datetime.now(ZoneInfo("Europe/Berlin")).date()`. One line, nothing else changes.
|
||||||
|
- **If we skip it:** Late orders show the wrong date, and accounting fixes them by hand.
|
||||||
|
|
||||||
|
End with:
|
||||||
|
- `Verdict:` one line: healthy, or what to fix first.
|
||||||
|
- `Lean: -<N> lines, -<M> dependencies possible.` when lean findings exist.
|
||||||
|
- `Not checked:` the parts you did not read or could not run.
|
||||||
|
|
||||||
|
Nothing found: `What this repo does:`, then `Healthy. Nothing to fix.` and
|
||||||
|
one line on what you checked.
|
||||||
|
|
||||||
|
One-shot report, changes no code.
|
||||||
@@ -0,0 +1,44 @@
|
|||||||
|
---
|
||||||
|
name: ponytail-debt
|
||||||
|
description: >
|
||||||
|
List every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report,
|
||||||
|
changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the
|
||||||
|
shortcuts", /ponytail-debt.
|
||||||
|
---
|
||||||
|
|
||||||
|
Every deliberate ponytail shortcut is marked with a `shortcut:` comment naming
|
||||||
|
its ceiling and upgrade path (older code may say `ponytail:`). This collects them into one ledger so a deferral
|
||||||
|
can't quietly become permanent.
|
||||||
|
|
||||||
|
## Scan
|
||||||
|
|
||||||
|
Grep the repo for comment markers, skipping `.git` and everything the
|
||||||
|
`.gitignore` files ignore (dependencies, build output, caches, in any stack):
|
||||||
|
|
||||||
|
`git grep --no-index --exclude-standard -nE '(#|//|/[*]) ?(shortcut|ponytail):'` (add other comment prefixes if your stack uses them)
|
||||||
|
|
||||||
|
If the user names their own marker word (`/ponytail-debt TODO`), grep for that word instead.
|
||||||
|
|
||||||
|
Each hit is one ledger row. The comment prefix keeps prose that merely mentions
|
||||||
|
the convention out of the ledger. Skip hits that are not a deferral, like a note
|
||||||
|
about a keyboard shortcut.
|
||||||
|
|
||||||
|
## Output
|
||||||
|
|
||||||
|
One row per marker, grouped by file:
|
||||||
|
|
||||||
|
`<file>:<line>, <what was simplified>. ceiling: <the limit named>. upgrade: <the trigger to revisit>.`
|
||||||
|
|
||||||
|
The convention is `shortcut: <ceiling>, <upgrade path>`, so pull the ceiling
|
||||||
|
and the trigger straight from the comment. Want an owner per row too? add
|
||||||
|
`git blame -L<line>,<line>`.
|
||||||
|
|
||||||
|
Flag the rot risk: any marker comment that names no upgrade path or
|
||||||
|
trigger gets a `no-trigger` tag, those are the ones that silently rot.
|
||||||
|
|
||||||
|
End with `<N> markers, <M> with no trigger.` Nothing found: `No shortcut debt. Clean ledger.`
|
||||||
|
|
||||||
|
## Boundaries
|
||||||
|
|
||||||
|
Reads and reports only, changes nothing. To persist it, ask and it writes the
|
||||||
|
ledger to a file (e.g. `PONYTAIL-DEBT.md`). One-shot.
|
||||||
@@ -0,0 +1,52 @@
|
|||||||
|
---
|
||||||
|
name: ponytail-gain
|
||||||
|
description: >
|
||||||
|
Show ponytail's measured savings (code, cost, speed) from the benchmark.
|
||||||
|
One-shot display. Use for /ponytail-gain, "what does ponytail save",
|
||||||
|
"ponytail impact".
|
||||||
|
---
|
||||||
|
|
||||||
|
# Ponytail Gain
|
||||||
|
|
||||||
|
Display this scoreboard when invoked. One-shot: do NOT change mode, write flag
|
||||||
|
files, or persist anything.
|
||||||
|
|
||||||
|
The figures are the published agentic benchmark of Ponytail 5: headless Claude
|
||||||
|
Code (Opus 5.5, default effort) on 39 tasks (feature tickets in a real FastAPI +
|
||||||
|
React repo, bug fixes, security and privacy cases, small apps), 5 runs each,
|
||||||
|
against the same agent without the skill. 18 of the tasks have hidden checks
|
||||||
|
for correctness and safety. Each figure is the geometric mean of the per-task
|
||||||
|
medians. They are measured, not computed from the current repo.
|
||||||
|
Source: `benchmarks/results/2026-10-07-agentic.md` and the README.
|
||||||
|
|
||||||
|
## Scoreboard
|
||||||
|
|
||||||
|
Render plain ASCII bars. The bar length shows ponytail as a share of the
|
||||||
|
no-skill baseline; the label carries the exact figure:
|
||||||
|
|
||||||
|
```
|
||||||
|
ponytail gain benchmark · 39 tasks × 5 runs · Opus 5.5
|
||||||
|
|
||||||
|
no-skill ████████████████████ 100%
|
||||||
|
Lines of code █████████··········· 47% ▼ 53%
|
||||||
|
Output tokens ███████████········· 55% ▼ 45%
|
||||||
|
Cost ███████████████····· 74% ▼ 26%
|
||||||
|
Time ████████████········ 59% ▼ 41%
|
||||||
|
Hidden checks passed 97% (no-skill 96%)
|
||||||
|
Tests where the logic needs one 98% (no-skill 68%)
|
||||||
|
|
||||||
|
This repo: /ponytail-debt (shortcuts you deferred)
|
||||||
|
/ponytail-audit (what's still cuttable)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Honesty boundary
|
||||||
|
|
||||||
|
These are benchmark averages, not this repo. NEVER print a per-repo savings
|
||||||
|
number ("you saved X lines/tokens here"): the unbuilt version was never
|
||||||
|
written, so there is no real baseline to subtract from in a live repo. The
|
||||||
|
only real per-repo figures come from `/ponytail-debt` (a counted ledger), and
|
||||||
|
this card points there instead of inventing one.
|
||||||
|
|
||||||
|
## Boundaries
|
||||||
|
|
||||||
|
One-shot display. Edits nothing, changes no mode.
|
||||||
@@ -0,0 +1,76 @@
|
|||||||
|
---
|
||||||
|
name: ponytail-help
|
||||||
|
description: >
|
||||||
|
Quick reference for ponytail levels, skills and commands. One-shot display.
|
||||||
|
Use for /ponytail-help, "ponytail help", "how do I use ponytail".
|
||||||
|
---
|
||||||
|
|
||||||
|
# Ponytail Help
|
||||||
|
|
||||||
|
Display this reference card when invoked. One-shot, do NOT change mode,
|
||||||
|
write flag files, or persist anything.
|
||||||
|
|
||||||
|
## Levels
|
||||||
|
|
||||||
|
| Level | Trigger | What change |
|
||||||
|
|-------|---------|-------------|
|
||||||
|
| **Lite** | `/ponytail lite` | Build what was asked, name the smaller option in one line. |
|
||||||
|
| **Full** | `/ponytail` | The smallest complete change, a check where the logic needs one, and a reply that names what was skipped and any risk. Default. |
|
||||||
|
| **Ultra** | `/ponytail ultra` | Also questions the request and pushes back before building. |
|
||||||
|
|
||||||
|
Level sticks until changed or session end.
|
||||||
|
|
||||||
|
## Skills
|
||||||
|
|
||||||
|
| Skill | Trigger | What it does |
|
||||||
|
|-------|---------|--------------|
|
||||||
|
| **ponytail** | `/ponytail` | Lazy mode itself: least new code, clear replies that name skipped work and risks. |
|
||||||
|
| **ponytail-review** | `/ponytail-review` | Quality review of a diff: bugs, security, load, missing tests, speed, what to cut. Each finding says what goes wrong and how to fix it. |
|
||||||
|
| **ponytail-audit** | `/ponytail-audit` | The same quality review for the whole repo, ranked. |
|
||||||
|
| **ponytail-debt** | `/ponytail-debt` | Harvest `shortcut:` comments into a tracked ledger. |
|
||||||
|
| **ponytail-gain** | `/ponytail-gain` | Measured-impact scoreboard: less code, less cost, more speed. |
|
||||||
|
| **ponytail-help** | `/ponytail-help` | This card. |
|
||||||
|
|
||||||
|
In Codex CLI and the IDE extension, invoke skills with `$ponytail:ponytail`,
|
||||||
|
`$ponytail:ponytail-review`, or `$ponytail:ponytail-help`. Claude Code and OpenCode use the
|
||||||
|
slash-command forms above (OpenCode ships all six as slash commands).
|
||||||
|
|
||||||
|
## Deactivate
|
||||||
|
|
||||||
|
Say "stop ponytail" or "normal mode". Resume anytime with `/ponytail`.
|
||||||
|
`/ponytail off` also works.
|
||||||
|
|
||||||
|
## Band (Claude Code)
|
||||||
|
|
||||||
|
`/ponytail band` hides the band above the prompt, the same command brings it back.
|
||||||
|
`/ponytail band on` and `/ponytail band off` set it directly. The level stays.
|
||||||
|
`/ponytail band import` adds your past Claude Code sessions (cost, agent time, tokens) to the board.
|
||||||
|
|
||||||
|
## Configure Default Mode
|
||||||
|
|
||||||
|
Default mode = `full`, auto-active every session. Change it:
|
||||||
|
|
||||||
|
**Environment variable** (highest priority):
|
||||||
|
```bash
|
||||||
|
export PONYTAIL_DEFAULT_MODE=ultra
|
||||||
|
```
|
||||||
|
|
||||||
|
**Config file** (`~/.config/ponytail/config.json`, Windows: `%APPDATA%\ponytail\config.json`):
|
||||||
|
```json
|
||||||
|
{ "defaultMode": "lite" }
|
||||||
|
```
|
||||||
|
|
||||||
|
Set `"off"` to disable auto-activation on session start, activate manually
|
||||||
|
with `/ponytail` when wanted.
|
||||||
|
|
||||||
|
Resolution: env var > config file > `full`.
|
||||||
|
|
||||||
|
## Update
|
||||||
|
|
||||||
|
Enable auto-update once: open `/plugin`, go to Marketplaces, pick ponytail, Enable auto-update. Claude Code then pulls new versions at startup (run `/reload-plugins` when it prompts). Manual refresh: `/plugin marketplace update ponytail` then `/reload-plugins`.
|
||||||
|
|
||||||
|
If `/plugin` is not recognized, your Claude Code is out of date. Update it (`npm install -g @anthropic-ai/claude-code@latest`, or `brew upgrade claude-code`) and restart. Other hosts use their own update flow.
|
||||||
|
|
||||||
|
## More
|
||||||
|
|
||||||
|
Full docs + examples: https://github.com/DietrichGebert/ponytail
|
||||||
@@ -0,0 +1,101 @@
|
|||||||
|
---
|
||||||
|
name: ponytail-review
|
||||||
|
description: >
|
||||||
|
Quality review of a change: is the logic right, is it safe, does it hold
|
||||||
|
under real load, is risky code tested, is it fast enough, and is every line
|
||||||
|
needed. Reads the connected code, not only the diff. Each finding is
|
||||||
|
explained in plain English. Use for "review this", "code review", "review
|
||||||
|
the last commit", "review my PR", "is this over-engineered", /ponytail-review.
|
||||||
|
---
|
||||||
|
|
||||||
|
Review a change like the senior developer who will be paged when it breaks.
|
||||||
|
Order of importance: correct, safe, holds under load, tested, fast, lean.
|
||||||
|
Lean still matters: every extra line must be read, tested and fixed later.
|
||||||
|
This is a report the user asked for, so give it in full.
|
||||||
|
|
||||||
|
## 1. Understand first
|
||||||
|
|
||||||
|
- Review what the user names: uncommitted or staged changes, a branch, a PR
|
||||||
|
link, or files. Nothing named: the uncommitted changes, or the last commit
|
||||||
|
if there are none.
|
||||||
|
- Read the diff, then the code it touches: callers of every changed function,
|
||||||
|
the functions it calls, the tests, the README.
|
||||||
|
- Trace the real flow: where data comes in, what is stored, what goes out.
|
||||||
|
- A change can break code it does not touch. When a signature, return value
|
||||||
|
or behavior changes, grep every caller.
|
||||||
|
- Find the expected load in the repo (README, deploy config): one person
|
||||||
|
running a script, or many users and processes at once. Judge scale against
|
||||||
|
that, and say which load you assumed.
|
||||||
|
|
||||||
|
## 2. Look for
|
||||||
|
|
||||||
|
1. **Bug:** wrong result, crash, missed edge case (empty, zero, last item,
|
||||||
|
rounding, time zones), a caller broken by the change, a fix applied in one
|
||||||
|
caller while the shared function stays broken.
|
||||||
|
2. **Risk:** security holes (injection, weak randomness, secrets, missing
|
||||||
|
checks on input from users), data loss (errors swallowed, writes in the
|
||||||
|
wrong order, no transaction).
|
||||||
|
3. **Scale:** fine for one user, wrong for many: check-then-write races, the
|
||||||
|
same work done by every process, memory or lists that only grow, a query
|
||||||
|
per item, O(n^2) on big input, per-process state that must be shared.
|
||||||
|
4. **Missing test:** risky new logic (a branch, a parser, money, security,
|
||||||
|
data writes, a bug fix) with no test that fails when it breaks. One good
|
||||||
|
test, not coverage.
|
||||||
|
5. **Speed:** big slowdowns are problems. Small wins (work repeated in a hot
|
||||||
|
loop) are suggestions; some software counts every millisecond.
|
||||||
|
6. **Lean:** code that should not exist or should be smaller.
|
||||||
|
- delete: dead code, unused options, speculative features
|
||||||
|
- reuse: the repo already has this helper (name the path)
|
||||||
|
- stdlib / native: the standard library or platform already does it; a
|
||||||
|
new dependency for a few lines
|
||||||
|
- yagni: abstraction with one implementation, config nobody sets
|
||||||
|
- merge: near-copies that must change together
|
||||||
|
- split: one function doing several unrelated jobs, so it is hard to read
|
||||||
|
or test. Split by job, never by line count, and never into helpers that
|
||||||
|
exist only to make a function shorter.
|
||||||
|
|
||||||
|
## 3. Check before you report
|
||||||
|
|
||||||
|
- Every finding needs a concrete case: "this input or situation leads to this
|
||||||
|
wrong result". No case, no finding.
|
||||||
|
- Re-read the lines and confirm: the caller exists, the value can really be
|
||||||
|
empty, the code really is unused.
|
||||||
|
- A shortcut marked with a `shortcut:` (or older `ponytail:`) comment that names its limit is a
|
||||||
|
decision, not a finding, unless the expected load already crosses it.
|
||||||
|
- Propose the smallest fix that works. Prefer fixes that delete code. Never
|
||||||
|
add layers, frameworks or config the problem does not need.
|
||||||
|
- No style taste, no "consider", no vague worries.
|
||||||
|
|
||||||
|
## 4. Output
|
||||||
|
|
||||||
|
Very simple English: short sentences, everyday words. Explain a technical
|
||||||
|
term the first time you use it. The reader may never have seen this code.
|
||||||
|
|
||||||
|
Start with `What this change does:` in two or three sentences.
|
||||||
|
|
||||||
|
Then the findings in three groups, skip empty groups:
|
||||||
|
- **Must fix:** bug, security, data loss, breaks at the expected load.
|
||||||
|
- **Should fix:** risky code without a test, real slowness, duplication, a
|
||||||
|
function that mixes jobs, code that should not exist.
|
||||||
|
- **Nice to have:** small speed-ups, shorter forms.
|
||||||
|
|
||||||
|
Number findings across all groups, so the user can say "fix 2 and 5".
|
||||||
|
Every finding has all four parts, each one or two short sentences:
|
||||||
|
|
||||||
|
2. **Orders land on the wrong day** (`billing/close_day.py:L40-52`)
|
||||||
|
- **What this is:** At midnight this job closes the day and bills all orders of that day.
|
||||||
|
- **Problem:** It takes "today" from the server clock, which runs in UTC. An order placed
|
||||||
|
at 00:30 in Berlin is billed on the day before.
|
||||||
|
- **Fix:** Compute the day once in the shop's time zone:
|
||||||
|
`datetime.now(ZoneInfo("Europe/Berlin")).date()`. One line, nothing else changes.
|
||||||
|
- **If we skip it:** Late orders show the wrong date, and accounting fixes them by hand.
|
||||||
|
|
||||||
|
End with:
|
||||||
|
- `Verdict: Ship.` or `Verdict: fix 1 and 3 first.`
|
||||||
|
- `Lean: -<N> lines possible.` when lean findings exist.
|
||||||
|
- `Not checked:` one line, if something mattered and you could not check it.
|
||||||
|
|
||||||
|
Nothing found: `What this change does:`, then `Looks good. Ship.` and one line
|
||||||
|
on what you checked.
|
||||||
|
|
||||||
|
Lists findings, changes no code.
|
||||||
@@ -0,0 +1,52 @@
|
|||||||
|
---
|
||||||
|
name: ponytail
|
||||||
|
description: >
|
||||||
|
Lazy senior dev mode: the smallest change that fully solves the task, and a
|
||||||
|
reply a busy human understands in one read. Use on any coding task (writing,
|
||||||
|
fixing, refactoring, reviewing, choosing dependencies) and when the user says
|
||||||
|
"ponytail", "be lazy", "simplest solution", "yagni", or complains about
|
||||||
|
over-engineering or bloat. Levels: lite, full (default), ultra.
|
||||||
|
argument-hint: "[lite|full|ultra|off]"
|
||||||
|
license: MIT
|
||||||
|
---
|
||||||
|
|
||||||
|
# Ponytail
|
||||||
|
|
||||||
|
You are a lazy senior developer. The best code is the code never written. You solve the whole problem with the least new code. End your reply with one or two lines: what you skipped or did not check, and any risk the user must know.
|
||||||
|
|
||||||
|
Active for the whole session until the user says "stop ponytail" or "normal mode". Switch level: `/ponytail lite|full|ultra`.
|
||||||
|
|
||||||
|
## Before you write
|
||||||
|
|
||||||
|
Read the task and the code it touches. List every place your change must reach: callers, tests, fixtures, config, exports. Check what your change could break for users: data it would destroy or expose, callers that stop working. That is scope. Extra features are not.
|
||||||
|
|
||||||
|
## The smallest complete change
|
||||||
|
|
||||||
|
Take the first option that fully works:
|
||||||
|
|
||||||
|
1. Does it need to exist? Skip features, options and flexibility nobody asked for, and name them in one line. A vague request ("build me X") gets the smallest version that does the core job.
|
||||||
|
2. Already in this codebase (a helper, component, service, pattern)? Use it the way the surrounding code does.
|
||||||
|
3. Standard library or a platform feature? Use it, unless the project has its own. A house component beats a native widget.
|
||||||
|
4. An installed dependency? Use it. Never add a dependency for a few lines.
|
||||||
|
5. Can it be one line a reader gets at a glance? One line.
|
||||||
|
6. Otherwise: the minimum code that works.
|
||||||
|
|
||||||
|
- Be lazy about the solution, never about the change itself: finish every part the task needs, including the callers, tests and fixtures your change breaks.
|
||||||
|
- No abstraction, wrapper, type conversion, option, config, boilerplate or "for later" code nobody asked for. Keep values in the form the platform already gives you. Deletion beats addition. Keep the structure the codebase already has: its layers, interfaces and conventions.
|
||||||
|
- The shortest working diff wins, once you know everything it must touch. A one-liner that needs decoding is not short.
|
||||||
|
- Comment only the why the code cannot show, in one line.
|
||||||
|
- Bug fix: before you edit, grep every caller of the function you touch, then fix the root cause once in the shared code.
|
||||||
|
- Code you move or merge keeps its error handling and validation.
|
||||||
|
- Between options of equal size, take the one that is correct on edge cases.
|
||||||
|
- Lazy code without its check is unfinished: new non-trivial logic (a branch, a loop, a parser, money or security, or a whole new script or app) leaves one small test or an assert-based self-check. Trivial changes need none.
|
||||||
|
- A shortcut with a known limit gets a code comment in this form: `shortcut: <the limit>, <when to upgrade>`.
|
||||||
|
|
||||||
|
Never cut: validation at trust boundaries, error handling that prevents data loss, security, accessibility, the calibration real hardware needs, anything the user asked for.
|
||||||
|
|
||||||
|
## Levels
|
||||||
|
|
||||||
|
| Level | Behavior |
|
||||||
|
|-------|----------|
|
||||||
|
| **lite** | Build what was asked. Name the smaller option in one line and let the user pick. |
|
||||||
|
| **full** | The rules above. Default. |
|
||||||
|
| **ultra** | Also question the request: before building, push back on any part the need does not justify. |
|
||||||
@@ -0,0 +1,342 @@
|
|||||||
|
---
|
||||||
|
name: reverse-engineer-anything
|
||||||
|
description: Reverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.
|
||||||
|
metadata:
|
||||||
|
version: "42"
|
||||||
|
tool_count: 207
|
||||||
|
---
|
||||||
|
|
||||||
|
# REA
|
||||||
|
|
||||||
|
Use REA when a claim depends on a shipped binary or package, decompilation,
|
||||||
|
passive application runtime evidence, or comparison with
|
||||||
|
behavior not established by available source. For ordinary analysis of a
|
||||||
|
complete source repository, use normal repository tools and do not run REA
|
||||||
|
readiness or provider commands.
|
||||||
|
|
||||||
|
## Connect only when needed
|
||||||
|
|
||||||
|
Installing this skill supplies instructions; it does not register the REA MCP
|
||||||
|
server, install analysis engines, or add tools to an already-running agent.
|
||||||
|
|
||||||
|
If REA tools are available and their registration is not known to be stale,
|
||||||
|
proceed directly to the target. Do not run diagnostics or setup before every
|
||||||
|
investigation. Use the connected server's actual tool list and input schemas;
|
||||||
|
a skill installed from repository main may describe capabilities absent from
|
||||||
|
an older npm release. Keep complete inline Evidence when that server does not
|
||||||
|
advertise retained references.
|
||||||
|
|
||||||
|
If tools are absent, a call is blocked by the client, or a required provider is
|
||||||
|
unavailable, read [connection and recovery](references/connection-and-recovery.md).
|
||||||
|
Diagnose the observed blocker, continue useful supported work, and resume the
|
||||||
|
original task after repair. Client approval, shell PATH, registration and engine
|
||||||
|
availability have different remedies; avoid repeating setup for all of them.
|
||||||
|
|
||||||
|
1. Diagnose without changing REA or client configuration. `npx` may download
|
||||||
|
the package and write to npm's cache. For Codex, run
|
||||||
|
`npx -y rea-agents@6.5.0 doctor --client codex --json`. Substitute the current
|
||||||
|
supported client: `claude_code`, `claude_desktop`, `codex`, `cursor`,
|
||||||
|
`gemini_cli`, `windsurf`, `devin`, `opencode`, `antigravity`, `copilot_cli`,
|
||||||
|
`commandcode`, `vscode`, `grok_build`, `omp`, or `grok_bot`. `grok_bot` has no local
|
||||||
|
file registration: doctor reports the Grok Bot chat step, and setup does not
|
||||||
|
write `mcp.json`. If the client is unknown, use `doctor --json` and
|
||||||
|
inspect its registration results before choosing a setup scope.
|
||||||
|
2. Distinguish the reason. Missing, malformed, or stale registration needs a
|
||||||
|
scoped configuration repair. An aligned registration with no tools in the
|
||||||
|
active session needs a restart/reconnection; doctor cannot prove that the
|
||||||
|
current agent has connected. A missing provider affects only tasks requiring
|
||||||
|
that provider: static JavaScript inspection needs neither Hopper nor Ghidra,
|
||||||
|
and Android inspection has separate bring-your-own JADX/Java prerequisites.
|
||||||
|
3. For a configuration repair, prepare the read-only plan:
|
||||||
|
`npx -y rea-agents@6.5.0 setup --client codex --dry-run --json`.
|
||||||
|
Use the current client's ID, show its exact proposed paths, backups, and
|
||||||
|
changes, and obtain approval before setup writes configuration or installs
|
||||||
|
Hopper. Setup normally installs the matching bundled skill too; include that
|
||||||
|
replacement in the reviewed plan. After approval, apply the same scope with
|
||||||
|
`npx -y rea-agents@6.5.0 setup --client codex --yes`. Add `--install-hopper`
|
||||||
|
only if that separate installation was needed and explicitly approved.
|
||||||
|
4. Restart/reconnect the affected agent. Verify that REA tools actually appear
|
||||||
|
in the session, then resume the original investigation. If they remain
|
||||||
|
absent, inspect the client's MCP launch error rather than repeating setup.
|
||||||
|
|
||||||
|
REA setup never installs or upgrades Node.js, npm, Homebrew, Java, Ghidra, IDA,
|
||||||
|
JADX, Binwalk, or Unblob. Use existing prerequisites; do not install unrelated
|
||||||
|
software to repair
|
||||||
|
MCP registration. For an unsupported client, use manual stdio registration
|
||||||
|
with a version-pinned `rea-agents` package or continue through the CLI.
|
||||||
|
|
||||||
|
A concrete CLI fallback for an operator-supplied JavaScript tree or ASAR is:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx -y rea-agents@6.5.0 analyze-javascript-application /absolute/path/to/app --json
|
||||||
|
```
|
||||||
|
|
||||||
|
No MCP registration or native engine is required. Read the returned Evidence,
|
||||||
|
graph, limitations, and unknowns with the same care as an MCP result; the CLI
|
||||||
|
returns the Evidence record directly. This fallback does not establish that
|
||||||
|
MCP is configured. Native CLI tasks still require their selected engine.
|
||||||
|
Prefer an existing `rea` CLI. When none is installed and REA package acquisition
|
||||||
|
is within the authorized scope, use `npx -y rea-agents@6.5.0` in its place.
|
||||||
|
Configuration repair starts with a read-only setup plan; show paths, backups and
|
||||||
|
skill replacement before applying authorized changes. Preserve existing approval
|
||||||
|
and target-execution boundaries. REA setup never installs or upgrades unrelated
|
||||||
|
software, including Node.js, npm, Homebrew, Java, Ghidra, IDA, JADX, Binwalk or Unblob.
|
||||||
|
|
||||||
|
## Route the target first
|
||||||
|
|
||||||
|
Choose the first tool from the target the user supplied. Use `open_binary` for
|
||||||
|
active-target native or archive workflows; target-free tools take their own
|
||||||
|
explicit path or endpoint and do not need it.
|
||||||
|
|
||||||
|
- ASAR or extracted JavaScript/Electron tree:
|
||||||
|
`analyze_javascript_application`.
|
||||||
|
- Archive/package member inventory (ZIP/APK/IPA/MSIX/AppX or DMG):
|
||||||
|
`open_binary` with the supplied local path; use `inspect_artifact` when its
|
||||||
|
graph and findings help answer the question.
|
||||||
|
- Android APK code, classes, methods, or incoming references:
|
||||||
|
`inspect_android_package`, then focused Android tools when advertised.
|
||||||
|
Archive member inventory still uses the archive route above.
|
||||||
|
- Managed PE/CLI assembly: `inspect_managed_artifact`.
|
||||||
|
- Firmware image: `inspect_firmware_regions` when advertised. Use
|
||||||
|
`extract_firmware` when extraction is requested, with a caller-selected new
|
||||||
|
absolute output directory. These tools use caller-supplied Binwalk/Unblob on
|
||||||
|
Linux; see the [firmware guide](https://github.com/morluto/rea/blob/main/docs/firmware-analysis.md).
|
||||||
|
- .NET NativeAOT PE/ELF: native Ghidra analysis. Native code can yield pseudocode;
|
||||||
|
consult the NativeAOT workflow in `references/native-and-artifacts.md` for
|
||||||
|
optional metadata recovery and its supported host/layout boundary.
|
||||||
|
- User-owned browser page already open: `list_browser_targets`.
|
||||||
|
- Browser action the agent must perform (click, type, navigate):
|
||||||
|
`capture_browser_scenario` with declared actions. See
|
||||||
|
[runtime observation](references/runtime-observation.md) for connect/launch
|
||||||
|
and the focused follow-up browser tools.
|
||||||
|
- Fiddler Everywhere traffic or a native `.saz` capture: read the
|
||||||
|
[Fiddler workflow](references/runtime-observation.md#fiddler-everywhere-traffic-debugging).
|
||||||
|
Inspect saved SAZ with `inspect_web_network_capture` and `format: "saz"`;
|
||||||
|
connect Everywhere's separate MCP server for live traffic.
|
||||||
|
- Retained HAR/SAZ/native mitmproxy/aioquic qlog capture: `inspect_web_network_capture`. Select
|
||||||
|
original record ordinals when useful; inspect producer fields and byte/number
|
||||||
|
sidecars without fetching recorded URLs or claiming live attribution. See
|
||||||
|
[historical captures](https://github.com/morluto/rea/blob/main/docs/web-network-captures.md) for the exact upstream
|
||||||
|
profile and credential exclusions. Qlog support starts with aioquic 1.5.0
|
||||||
|
JSON 0.3; stream coverage and endpoint loss declarations do not recover bodies
|
||||||
|
or establish network loss. Prefer detail summary, then kind qlog trace/stream
|
||||||
|
pages; select one trace, stream ID and direction for contribution/range pages.
|
||||||
|
Facts retain all-recorded-events-before-selection scope. Other qlog layouts
|
||||||
|
and PCAP correlation are unsupported.
|
||||||
|
- User-owned Electron runtime already open: `list_electron_targets`. Before an electron-main Inspector attempt, check packaged fuses with `inspect_electron_fuses`; disabled `EnableNodeCliInspectArguments` means the app ignores `--inspect`.
|
||||||
|
- Packet-field discovery: `inspect_packet_fields` searches installed protocols
|
||||||
|
and field names/types before choosing fields for `inspect_packet_capture`.
|
||||||
|
Query/page the relevant records; registrations do not establish observed traffic.
|
||||||
|
- Recorded packet captures: `inspect_packet_capture` with selected TShark fields,
|
||||||
|
display filters and decode-as rules. Requires Linux, util-linux prlimit and `REA_TSHARK_COMMAND`; see
|
||||||
|
[capture guide](https://github.com/morluto/rea/blob/main/docs/packet-captures.md).
|
||||||
|
Packet limits count input packets before filtering. Output defaults to 50 matching
|
||||||
|
frames; use `match_offset` / `match_limit` for later pages, or explicit null
|
||||||
|
limit for complete matching output. Preserve the source digest across pages.
|
||||||
|
This does not perform live capture.
|
||||||
|
For address/DNS/SNI/protocol summaries use `inspect_pcap_capture` with MCP
|
||||||
|
detail summary, then retained kind pcap pages. Requires Wireshark 4.x tshark
|
||||||
|
and capinfos, with Linux prlimit or Windows Job Objects; see
|
||||||
|
[packet summaries](https://github.com/morluto/rea/blob/main/docs/pcap-analysis.md).
|
||||||
|
Select an exact DNS question for address pages; page exhaustion does not prove
|
||||||
|
network completeness. This reads recordings and does not acquire traffic.
|
||||||
|
- Decoder discovery: `inspect_signal_decoders` searches installed decoder IDs
|
||||||
|
or selected decoder help, including channels and options. Query and page the
|
||||||
|
relevant details before choosing settings; this does not scan hardware.
|
||||||
|
- Recorded logic/signal traces: `decode_signal_recording` with explicit decoder,
|
||||||
|
channel and protocol settings. On Linux with util-linux prlimit, supply sigrok-cli 0.7.2 through
|
||||||
|
`REA_SIGROK_COMMAND`; see [recording guide](https://github.com/morluto/rea/blob/main/docs/signal-recordings.md).
|
||||||
|
Output defaults to 50 literal lines; select annotation classes and page with
|
||||||
|
`line_offset` / `line_limit`, or explicit null for all remaining output.
|
||||||
|
Window counts are display lines, not annotations or samples. Preserve source digests across pages.
|
||||||
|
This reads existing files; it does not acquire hardware signals.
|
||||||
|
- Explicit local WebAssembly artifact: `inspect_wasm_artifact`. Supply WABT 1.0.42
|
||||||
|
through `REA_WABT_BIN_DIRECTORY`; retain exact byte/tool identity and decoded WAT.
|
||||||
|
Select JavaScript glue and candidate paths explicitly and preserve URL/path
|
||||||
|
ambiguity. No implicit fetch or target execution; WAT is not original source.
|
||||||
|
See the [WASM guide](https://github.com/morluto/rea/blob/main/docs/wasm-artifacts.md).
|
||||||
|
- Explicit local EVM bytecode carrier: `inspect_evm_interface` with caller-selected
|
||||||
|
`raw` or `hex` encoding. Preserve carrier/decoded digests and treat selectors,
|
||||||
|
argument strings and mutability as inferred candidates; this performs no chain
|
||||||
|
lookup or target execution. For the complete inferred interface without hex or
|
||||||
|
duplicate stdout, discover support and select `detail: "summary"`; complete
|
||||||
|
Evidence stays retained under its original identity. Use the returned
|
||||||
|
`parent_evidence_id` for exact function or `bytecode_hex`/stdout/stderr pages.
|
||||||
|
Candidate coverage does not establish interface completeness. See the
|
||||||
|
[EVM bytecode guide](https://github.com/morluto/rea/blob/main/docs/evm-bytecode.md).
|
||||||
|
- Embedded Go compiler, module or build-setting metadata: `inspect_go_binary`
|
||||||
|
with the explicit local file. This built-in target-free inspection requires no
|
||||||
|
Go installation or disassembler. Preserve raw module bytes and source ranges;
|
||||||
|
absent metadata does not prove a binary is not Go, and unparsed text records
|
||||||
|
remain explicit. See the
|
||||||
|
[Go binary guide](https://github.com/morluto/rea/blob/main/docs/go-binaries.md).
|
||||||
|
- Embedded cargo-auditable Rust dependency metadata: `inspect_rust_binary`
|
||||||
|
with the explicit local ELF, PE, or thin Mach-O file. This built-in
|
||||||
|
target-free inspection requires no Rust installation or disassembler. Preserve
|
||||||
|
package order, dependency indices, and the section file range. A missing
|
||||||
|
`.dep-v0` section is null metadata, not proof the binary has no dependencies.
|
||||||
|
A rustc commit hash is an inference from a read-only `/rustc/<40-hex>/` path.
|
||||||
|
See the
|
||||||
|
[Rust binary guide](https://github.com/morluto/rea/blob/main/docs/rust-binaries.md).
|
||||||
|
|
||||||
|
- Explicit local SQLite database snapshot: `inspect_sqlite_database`. Inspect
|
||||||
|
with Node.js 24.x >=24.15 or 26+ providing native SQLite limits. Read schema
|
||||||
|
first (compact inventory by default), or select an exact ordinary table
|
||||||
|
and `columns` when rows are needed. Defaults are selected-table schema and
|
||||||
|
20 rows; request `schema_scope: "database"` for the complete stored schema. Preserve both database and existing sibling WAL identity; row samples
|
||||||
|
report truncation and have unspecified order. Use a quiescent snapshot rather
|
||||||
|
than assuming a live database/WAL pair was copied atomically. See the
|
||||||
|
[SQLite guide](https://github.com/morluto/rea/blob/main/docs/sqlite-databases.md).
|
||||||
|
- Explicit Linux ELF file for offline layout, symbols, relocations or static
|
||||||
|
mitigation evidence: `inspect_binary_layout`. This target-free operation uses
|
||||||
|
caller-supplied pwntools without opening a disassembler database. Preserve its
|
||||||
|
raw locations and inference/coverage limits; see the
|
||||||
|
[offline binary guide](https://github.com/morluto/rea/blob/main/docs/binary-diagnostics.md).
|
||||||
|
- Supplied Linux x86-64 ELF core: `inspect_recorded_crash`. Read every recorded
|
||||||
|
thread, raw note and source-bound register without opening a live target.
|
||||||
|
Historical PIDs do not select live processes. Request `include_debugger_context`
|
||||||
|
only when core-only mapping candidates help; see the
|
||||||
|
[recorded crash guide](https://github.com/morluto/rea/blob/main/docs/recorded-crashes.md).
|
||||||
|
- PE resource type/name/language trees and static icon group references:
|
||||||
|
`inspect_pe_resources` with an explicit path. This portable operation requires
|
||||||
|
no active target or engine; opaque payloads retain file ranges and SHA-256.
|
||||||
|
- Native executable, library, or analysis database: `open_binary`, then
|
||||||
|
use focused analysis tools directly; call `binary_overview` when metadata or
|
||||||
|
inventory context is useful and available from the selected provider.
|
||||||
|
|
||||||
|
For an existing IDA MCP configuration, use `open_binary` with the original
|
||||||
|
input binary and `provider_id: "ida"`; do not pass an `.idb` or `.i64` database.
|
||||||
|
The legacy attached profile binds the already-open GUI input by SHA-256 and
|
||||||
|
leaves its database open. The modern headless profile creates and closes an
|
||||||
|
owned private database without saving. Installation and registration reuse
|
||||||
|
[mrexodia/ida-pro-mcp](https://github.com/mrexodia/ida-pro-mcp); see the
|
||||||
|
[IDA provider guide](https://github.com/morluto/rea/blob/main/docs/ida-provider.md).
|
||||||
|
Proceed directly to `analyze_function`, pseudocode, or function/string searches
|
||||||
|
after opening; IDA does not supply `binary_overview`. Consult session availability
|
||||||
|
when composing broader workflows. Modern direct callers and unsupported dossier
|
||||||
|
facets remain unknown; live IDA results are not replayed from snapshots.
|
||||||
|
|
||||||
|
If the user says only "my app" without a name, path, or target already selected
|
||||||
|
for this task, ask which app before searching for artifacts. Paths in unrelated
|
||||||
|
saved reports and nearby test fixtures do not select the user's target. Resolve
|
||||||
|
an actual human-readable app name to one clear installed artifact when possible;
|
||||||
|
ask when matches are ambiguous. Never choose an example app on the user's behalf.
|
||||||
|
|
||||||
|
In a target-free session, use `open_binary` to bind any archive/package or
|
||||||
|
native target whose analysis tool operates on the active target. Do not call an
|
||||||
|
unadvertised tool; inspect `binary_session` with `{}` and its
|
||||||
|
`result.tool_availability` for availability reasons and remediation. Expand each
|
||||||
|
group's `names` into entries, inheriting the inventory-level client requirements
|
||||||
|
unless the group overrides them. In its closed effect and annotation vocabularies,
|
||||||
|
listed flags are true and omitted known flags are false. The grouped name union
|
||||||
|
is the complete tool inventory; use `tools/list` for canonical tool schemas.
|
||||||
|
Provider candidate facts describe possible providers, while top-level session
|
||||||
|
capabilities describe the current route and `analysis_provider_binding` names the
|
||||||
|
selected provider. Do not treat those scopes as interchangeable.
|
||||||
|
|
||||||
|
## Work summary-first
|
||||||
|
|
||||||
|
Start with the default result and use its inline Evidence and graph context.
|
||||||
|
For a JavaScript application or ELF layout whose size is unknown or large,
|
||||||
|
call `analyze_javascript_application` or `inspect_binary_layout` with
|
||||||
|
`"detail": "summary"`, then inspect the retained `parent_evidence_id` with
|
||||||
|
`inspect_analysis_view`.
|
||||||
|
Page module identities and select the returned `node_id` before requesting an
|
||||||
|
item; a single file path can represent several graph roles. Do not repeat an
|
||||||
|
identical analysis or rejected call without a changed input or resolved blocker.
|
||||||
|
Recheck session state when a lifecycle change makes that status useful.
|
||||||
|
Make a focused follow-up only when the
|
||||||
|
returned result leaves a specific question unanswered.
|
||||||
|
|
||||||
|
If MCP reports `resource_constraint` with `details.resource: "transport"`, call
|
||||||
|
`inspect_analysis_view` with its reported same-session Evidence reference for a
|
||||||
|
summary, one section/module, or a stable page. Use `trace_application_feature`
|
||||||
|
once a seed is known, or call `export_evidence_bundle` to write the complete
|
||||||
|
session to a selected path. The analysis remains complete in the ledger; avoid
|
||||||
|
repeating it merely to request the same oversized response. Complete CLI JSON
|
||||||
|
output also streams without a single MCP frame.
|
||||||
|
|
||||||
|
When the retained parent ID is unknown, use `get_evidence_bundle` with
|
||||||
|
`detail: "summary"` and exact filters for operation, target SHA-256,
|
||||||
|
analysis-profile digest or canonical procedure address. Select its returned
|
||||||
|
Evidence ID for the next view instead of requesting the complete bundle.
|
||||||
|
`retention: "complete-record"` means the whole record is stored; native
|
||||||
|
value-flow truncation and unknown metadata remain separate. For an exported
|
||||||
|
portable bundle, use `rea inspect-evidence-bundle` with JSON containing `path`,
|
||||||
|
`detail: "summary"` and the same `filters`. Reading that file still requires
|
||||||
|
validating its full contents within the local memory budget.
|
||||||
|
|
||||||
|
A client can also truncate a successful tool result without a REA transport
|
||||||
|
error. Treat that preview as incomplete; use the retained parent ID for smaller
|
||||||
|
views or export when the full record is needed. Do not parse the preview as
|
||||||
|
canonical JSON or repeat the producer. For JavaScript, read the
|
||||||
|
[module-view and trace recipes](references/javascript-applications.md) before
|
||||||
|
drilling into a large graph; a broad bidirectional trace can expand unrelated
|
||||||
|
containment relationships even after summary analysis.
|
||||||
|
|
||||||
|
Every conclusion must distinguish observations, inferences, and unknowns. Cite
|
||||||
|
Evidence IDs, preserve limitations and incomplete coverage, and never imply
|
||||||
|
that static analysis observed execution. Runtime requests execute the declared
|
||||||
|
target and lifecycle; do not broaden the target or action beyond those fields.
|
||||||
|
|
||||||
|
Within the user's requested investigation, call available analysis tools
|
||||||
|
directly. REA does not require permission grants or per-call approval flags.
|
||||||
|
The agent client can independently require approval. Follow the declared request
|
||||||
|
scope and the host's actual access requirements; use the recovery guide for an
|
||||||
|
observed client-policy rejection.
|
||||||
|
|
||||||
|
## Plan broader investigations
|
||||||
|
|
||||||
|
For requests that span multiple features or subsystems, use a staged workflow:
|
||||||
|
|
||||||
|
1. Turn the request into a checklist of questions and the evidence each answer
|
||||||
|
needs. Resolve target identity and constraints from the conversation and
|
||||||
|
workspace before asking for information again.
|
||||||
|
2. Inspect the current REA session, artifact identity, saved analysis database,
|
||||||
|
bookmarks, and prior evidence. Reuse matching state; do not open duplicate
|
||||||
|
sessions or repeat identical analysis.
|
||||||
|
3. Start with the smallest useful overview or inventory. Follow each question
|
||||||
|
from its entry point through relevant data and state changes to its result.
|
||||||
|
Batch related operations around a specific hypothesis, then expand only when
|
||||||
|
the returned evidence leaves a concrete gap.
|
||||||
|
4. Inspect relevant packaged resources and configuration alongside code when
|
||||||
|
they affect the question. Use format-aware inventory and parsers; do not
|
||||||
|
infer behavior from filenames, strings, or layout alone.
|
||||||
|
5. Corroborate a conclusion with the evidence type it requires. Use runtime
|
||||||
|
observation only when static evidence cannot answer the question and the
|
||||||
|
required host runtime and OS access are available. For JavaScript behavior,
|
||||||
|
run probes against the actual app through the available browser, Electron,
|
||||||
|
or process capture workflow.
|
||||||
|
6. Decompose work into independent questions. When parallel workers are
|
||||||
|
available and the questions do not depend on one another, assign distinct
|
||||||
|
scopes, point workers to existing evidence, and ask them to return sources,
|
||||||
|
conclusions, and unresolved gaps. Otherwise, work sequentially.
|
||||||
|
7. Keep a concise finding ledger linking each conclusion to Evidence IDs,
|
||||||
|
confidence/evidence type, search boundary, and remaining unknowns. Update
|
||||||
|
the shared index or investigation report so later passes can reuse results.
|
||||||
|
|
||||||
|
Before finishing, revisit the original checklist. Mark each question as
|
||||||
|
answered, partially answered, or unresolved based on its evidence; keep
|
||||||
|
bounded negative searches bounded, and do not describe a broad investigation
|
||||||
|
as complete while required questions remain open.
|
||||||
|
|
||||||
|
## Read only the relevant guide
|
||||||
|
|
||||||
|
- Native binaries, managed assemblies, archives, and extraction:
|
||||||
|
[references/native-and-artifacts.md](references/native-and-artifacts.md)
|
||||||
|
- ASARs, extracted JavaScript, feature tracing, and version comparison:
|
||||||
|
[references/javascript-applications.md](references/javascript-applications.md)
|
||||||
|
- Android APK declarations, classes, methods, and static references:
|
||||||
|
[references/android-applications.md](references/android-applications.md)
|
||||||
|
- Browser/Electron observation (passive and scenario) and static/runtime
|
||||||
|
reconciliation:
|
||||||
|
[references/runtime-observation.md](references/runtime-observation.md)
|
||||||
|
- Evidence paging, comparisons, residual unknowns, and verification:
|
||||||
|
[references/evidence-workflows.md](references/evidence-workflows.md)
|
||||||
|
|
||||||
|
## Finish the task
|
||||||
|
|
||||||
|
Explain findings in plain language and tie them to returned evidence. When the
|
||||||
|
user asks to build something, use normal coding tools and separate observed
|
||||||
|
behavior from design choices. Close an opened native session with
|
||||||
|
`close_binary` when the investigation is complete.
|
||||||
@@ -0,0 +1,34 @@
|
|||||||
|
# Android application artifacts
|
||||||
|
|
||||||
|
Use the connected server's advertised Android tools. Repository main and npm
|
||||||
|
4.1.0 include this family. A skill installation alone cannot add it to an
|
||||||
|
older server.
|
||||||
|
|
||||||
|
Start with `inspect_android_package` on the caller's APK path for package
|
||||||
|
identity, manifest declarations, coverage, and inline Evidence. Use
|
||||||
|
`search_android_classes` to find candidates, `inspect_android_class` for one
|
||||||
|
class's members, `inspect_android_method` for decompilation, and
|
||||||
|
`trace_android_references` for incoming static references. Each call takes its
|
||||||
|
own APK path and explicit selectors; do not open a native session first.
|
||||||
|
Choose an `overload_index` from the class inventory when methods are ambiguous
|
||||||
|
instead of guessing.
|
||||||
|
|
||||||
|
The provider requires a separately supplied headless JADX MCP JAR 0.7.1 and
|
||||||
|
Java 17 or newer. `REA_JADX_MCP_JAR` selects the absolute JAR path; `JAVA_HOME`
|
||||||
|
can select Java. REA setup does not install or configure that JAR, and doctor
|
||||||
|
provider scopes cover Hopper/Ghidra rather than JADX. Use existing tools and
|
||||||
|
report missing prerequisites for the Android task specifically.
|
||||||
|
|
||||||
|
Linux and macOS use the POSIX owned-process boundary. Windows x64 requires the
|
||||||
|
matching bundled native controls and uses an owned Job Object with bidirectional
|
||||||
|
stdio. A full JDK, including `jdk.compiler`, is required on every host; Windows
|
||||||
|
`JAVA_HOME` selects `bin\java.exe`. Consult the Android guide for actual host
|
||||||
|
verification coverage. Calls use one worker and provider deadlines; optional
|
||||||
|
`REA_JADX_HEAP_MIB` selects the JVM heap. The APK is never launched,
|
||||||
|
and no emulator is required.
|
||||||
|
|
||||||
|
Manifest entries and decompiled text are static observations, not execution or
|
||||||
|
policy enforcement. Incoming references are recovered static relationships;
|
||||||
|
reflection, dynamic loading, and unresolved calls remain unknown. Preserve
|
||||||
|
artifact digests, locations, diagnostics, and incomplete coverage. For archive
|
||||||
|
members rather than code analysis, use `open_binary` and `inspect_artifact`.
|
||||||
@@ -0,0 +1,127 @@
|
|||||||
|
# Connection and task recovery
|
||||||
|
|
||||||
|
Read this guide only for an observed connection, command, approval or provider
|
||||||
|
blocker. Keep the user's target and question in view. Explain what prevented the
|
||||||
|
operation and the next useful step; after repair, continue the investigation.
|
||||||
|
|
||||||
|
Commands below use an installed `rea`. If none is available, use the package
|
||||||
|
invocation in `SKILL.md` when acquiring REA is authorized. Follow the connected
|
||||||
|
server's schemas and the installed CLI's help rather than assuming repository
|
||||||
|
main and an older release expose the same arguments.
|
||||||
|
|
||||||
|
## Choose the remedy from the observed failure
|
||||||
|
|
||||||
|
| Observation | Meaning and next step |
|
||||||
|
| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||||
|
| No REA tools in the active session | Inspect registration with `rea doctor --client codex --json`. A skill installation alone does not register MCP. |
|
||||||
|
| Missing, malformed or stale registration | Prepare a scoped setup plan; apply only authorized changes with backups. |
|
||||||
|
| Aligned registration, but no connected tools | Restart/reconnect the client. Doctor checks registration; it cannot establish the current agent's connection. Inspect the client's launch error if reconnection fails. |
|
||||||
|
| `MCP tool call requires approval, but approval policy is never` | Codex rejected the call before REA executed it. Do not install an engine or repeat setup to solve this client-policy decision. See the approval section below. |
|
||||||
|
| REA returns `provider_unavailable` or an unavailable tool entry | Read that operation's provider diagnostics or `binary_session.result.tool_availability`. Expand each group's tool names and inherit the shared client requirements unless overridden. Use the operation's availability, reason, and remediation; a complete tool catalog does not imply every operation is available. |
|
||||||
|
| `rea` is missing in a child shell, or Node is incompatible | Inspect the actual shell PATH and launcher/runtime. A prefix installation may be absent from a login shell's PATH; this does not establish a broken MCP registration. |
|
||||||
|
|
||||||
|
If the client cannot launch its shell/sandbox helper or read the installed skill,
|
||||||
|
inspect its launch diagnostic. For example, Codex can refuse helper aliases when
|
||||||
|
CODEX_HOME is under `/tmp`; use an authorized profile outside the OS temporary
|
||||||
|
directory. REA setup cannot repair the client's executor. Preserve the sandbox
|
||||||
|
instead of silently disabling it to make an analysis command work.
|
||||||
|
|
||||||
|
Static JavaScript and ordinary ZIP inventory need neither Hopper nor Ghidra.
|
||||||
|
HAR inspection is offline and does not require a live browser. Native
|
||||||
|
decompilation, Android analysis and firmware extraction have their own
|
||||||
|
bring-your-own prerequisites. Use supported inventory/static evidence when it
|
||||||
|
answers part of the question, and name the unavailable evidence separately.
|
||||||
|
Do not substitute another target. Label observations from ordinary shell tools
|
||||||
|
as such; only actual REA output supplies REA Evidence.
|
||||||
|
|
||||||
|
## Repair registration when needed
|
||||||
|
|
||||||
|
For Codex:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
rea doctor --client codex --json
|
||||||
|
rea setup --client codex --dry-run --json
|
||||||
|
```
|
||||||
|
|
||||||
|
Use the current supported client's ID: `claude_code`, `claude_desktop`, `codex`,
|
||||||
|
`cursor`, `gemini_cli`, `windsurf`, `devin`, `opencode`, `antigravity`,
|
||||||
|
`copilot_cli`, `commandcode`, `qwen_code`, `vscode`, `trae`, `grok_build`, `omp`, `pi`,
|
||||||
|
`hermes`, `qoder`, `droid`, `zcode`, `dsh`, or `grok_bot`. If unknown, inspect `doctor --json` before choosing a
|
||||||
|
scope. `grok_bot` uses a chat registration step rather than local `mcp.json`.
|
||||||
|
For unsupported clients, use version-pinned manual stdio registration or CLI.
|
||||||
|
|
||||||
|
Show the plan's exact paths, backups, changes and bundled-skill replacement.
|
||||||
|
Obtain approval for writes when that concrete scope is not already authorized,
|
||||||
|
then apply the same scope with `rea setup --client codex --yes`. Add
|
||||||
|
`--install-hopper` only when separately needed and explicitly approved. Do not
|
||||||
|
install or upgrade unrelated prerequisites. Restart/reconnect, verify tools
|
||||||
|
actually appear, and resume the original task. If they remain absent, inspect
|
||||||
|
the launch failure rather than looping through setup.
|
||||||
|
|
||||||
|
## Codex tool approval is separate from REA readiness
|
||||||
|
|
||||||
|
REA tools have no permission-grant handshake. Codex can still require approval
|
||||||
|
because an operation creates owned resources, launches a helper or has cleanup
|
||||||
|
effects. An advertised tool or successful doctor result does not override that
|
||||||
|
client policy. `workspace-write` alone does not resolve an MCP approval
|
||||||
|
rejection, and `approval_policy = "never"` does not mean every MCP tool is
|
||||||
|
preapproved.
|
||||||
|
|
||||||
|
When interactive approval is available, use the client's approval flow for the
|
||||||
|
requested operation. In an unattended run, continue through an authorized CLI
|
||||||
|
workflow if the execution environment permits it, or report the blocked
|
||||||
|
operation and the approval needed to proceed. Do not retry the same rejected
|
||||||
|
call, silently broaden approvals, or rewrite MCP effects as read-only.
|
||||||
|
|
||||||
|
For an operator who explicitly wants to preapprove named operations in a
|
||||||
|
disposable Codex profile, current Codex supports per-tool configuration. For
|
||||||
|
example, opening and closing an analysis session can be scoped independently:
|
||||||
|
|
||||||
|
```toml
|
||||||
|
[mcp_servers.rea.tools.open_binary]
|
||||||
|
approval_mode = "approve"
|
||||||
|
|
||||||
|
[mcp_servers.rea.tools.close_binary]
|
||||||
|
approval_mode = "approve"
|
||||||
|
```
|
||||||
|
|
||||||
|
Use the actual server ID and only the operations whose effects were approved;
|
||||||
|
this example does not approve inspection, extraction or runtime execution.
|
||||||
|
Show the proposed config edit and preserve unrelated entries and backups before
|
||||||
|
writing. Managed policy can constrain client settings. Consult the
|
||||||
|
[Codex configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference)
|
||||||
|
for the installed client's supported settings. This is an optional recovery
|
||||||
|
choice, not a prerequisite for every REA task.
|
||||||
|
|
||||||
|
## Continue through an installed CLI
|
||||||
|
|
||||||
|
Check the command environment only if the launcher fails:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
command -v rea
|
||||||
|
command -v node
|
||||||
|
node --version
|
||||||
|
rea --version
|
||||||
|
```
|
||||||
|
|
||||||
|
Use the public launcher at its known installation path with a supported existing
|
||||||
|
Node on PATH when the child shell loses a prefix installation. Avoid internal
|
||||||
|
`dist/cli.js` entrypoints or global toolchain changes. MCP may have its own valid
|
||||||
|
launcher even when a shell cannot resolve `rea`.
|
||||||
|
|
||||||
|
For a user-supplied JavaScript tree or ASAR, select output files in the authorized
|
||||||
|
workspace and save complete Evidence before reading a view:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
rea analyze-javascript-application /absolute/path/to/app --json > app-evidence.json
|
||||||
|
jq -c '{source: {kind: "inline", evidence: .}, view: {kind: "summary"}}' app-evidence.json > app-view.json
|
||||||
|
rea inspect-analysis-view app-view.json
|
||||||
|
```
|
||||||
|
|
||||||
|
These commands do not register MCP or install an analysis engine. CLI JavaScript
|
||||||
|
JSON is complete and can be very large; redirect it rather than loading it into
|
||||||
|
context. Use an existing JSON processor if `jq` is absent, without installing
|
||||||
|
one just for this recipe. Inspect a module page or item using the same inline
|
||||||
|
source and the [JavaScript recipes](javascript-applications.md). Preserve graph
|
||||||
|
coverage, limitations and unknowns. Native CLI analysis still requires its
|
||||||
|
selected engine, and all CLI operations retain the host's execution permissions.
|
||||||
@@ -0,0 +1,71 @@
|
|||||||
|
# Evidence, comparison, and verification workflows
|
||||||
|
|
||||||
|
Evidence-producing tools return the complete Evidence record directly in MCP
|
||||||
|
`structuredContent` and CLI JSON. Read `normalized_result` for operation data,
|
||||||
|
and cite `evidence_id` when another tool or your explanation needs a stable
|
||||||
|
reference. Preserve authority, limitations, coverage, and residual unknowns. If a result
|
||||||
|
is incomplete or paginated, continue only when the remaining data matters to
|
||||||
|
the task; do not fetch a bundle or resource merely to read a result already
|
||||||
|
returned inline. When complete `inspect_binary_layout` or
|
||||||
|
`analyze_javascript_application` Evidence is already retained, call
|
||||||
|
`inspect_analysis_view` for a summary, one section/symbol/module, or a stable
|
||||||
|
page instead of repeating the producer.
|
||||||
|
|
||||||
|
Completed `inspect_artifact` inventory also supports a summary and
|
||||||
|
`view: {kind: "inventory", collection: "occurrences", logical_paths: ["package.json", "main.js"]}`.
|
||||||
|
Omit `logical_paths` to page all available occurrences; `[]` selects none.
|
||||||
|
Other inventory collections are `nodes`, `edges` and
|
||||||
|
`integrity_contradictions`. Keep `source_complete` separate from page exhaustion:
|
||||||
|
a missing match in partial source Evidence does not establish absence. Use the
|
||||||
|
returned parent Evidence ID for subsequent views and export before closing the
|
||||||
|
session when the source must survive it.
|
||||||
|
When `tools/list` advertises `inspect_artifact.detail`, request `"summary"` to
|
||||||
|
retain its complete source and receive that view immediately. Without that
|
||||||
|
advertised choice, keep the existing complete call. CLI inspection returns
|
||||||
|
portable complete Evidence; save it before projecting a selected inline view.
|
||||||
|
|
||||||
|
Use `record_unknown` to track unresolved questions in the user's investigation
|
||||||
|
and name the authority or environment still required. Supply supporting and
|
||||||
|
contradicting evidence IDs. It updates the session registry directly.
|
||||||
|
Use `update_unknown` with the current revision; reread after a stale revision
|
||||||
|
instead of retrying blindly. Only qualifying observed evidence can verify a
|
||||||
|
resolution.
|
||||||
|
|
||||||
|
Use comparisons with complete, compatible page sets when claiming equivalence
|
||||||
|
or absence:
|
||||||
|
|
||||||
|
- `compare_artifacts` compares inventory pages by occurrence path, content,
|
||||||
|
metadata, and graph relations.
|
||||||
|
- `compare_functions` compares explicit function Evidence, not fuzzy
|
||||||
|
whole-binary matches.
|
||||||
|
- `compare_bundles` compares canonical bundle membership and unknown history.
|
||||||
|
- `find_changed_behavior` combines existing comparisons; static differences
|
||||||
|
remain candidates, not causal proof.
|
||||||
|
- `build_call_path` needs explicit function dossiers from one artifact/provider;
|
||||||
|
an incomplete frontier makes absence unknown.
|
||||||
|
- `correlate_static_and_runtime` uses explicit mappings; matching patterns are
|
||||||
|
hypotheses, not causality.
|
||||||
|
- `verify_reconstruction` evaluates a finite typed specification. A pass covers
|
||||||
|
only declared comparable claims, not global equivalence.
|
||||||
|
|
||||||
|
Process captures are opt-in behavioral evidence, not a security sandbox. V3
|
||||||
|
captures cannot be upgraded to V4; rerun the original scenario. Distinguish root
|
||||||
|
exit from descendant settlement and require freshness when the task needs it.
|
||||||
|
A timed-out target that must write a final report needs `finalization_ms`: REA
|
||||||
|
sends SIGTERM to the captured root, keeps observing, and sends SIGKILL once
|
||||||
|
only if the target has not exited by the end of the interval.
|
||||||
|
`exit.finalization.signals` lists each attempt with its delivery result; the
|
||||||
|
observed exit signal stays in `exit.signal`, `exit.code` is null for every
|
||||||
|
deadline exit, and the code of a finalizer that exited on its own is in
|
||||||
|
`exit.finalization.exit_code` (null on a signal exit or when no exit was
|
||||||
|
observed).
|
||||||
|
|
||||||
|
Use `inspect_analysis_view` with `view: {kind: "api-surface"}` on retained
|
||||||
|
`inspect_web_network_capture` HAR Evidence to group observed request lines by
|
||||||
|
method, origin and path template. Format matches are inferences, not handler
|
||||||
|
identity or schemas. Group pages cite parent record ordinals; consult record
|
||||||
|
coverage and exclusions before claiming completeness. No requests are replayed.
|
||||||
|
When the connected schema advertises `include_query_parameter_names`, select
|
||||||
|
it in the view for distinct observed names with original record ordinals. Query
|
||||||
|
values are omitted; the names establish neither required parameters nor a
|
||||||
|
complete server schema. Keep the original parent Evidence for exact URLs.
|
||||||
@@ -0,0 +1,175 @@
|
|||||||
|
# JavaScript and Electron application artifacts
|
||||||
|
|
||||||
|
For captured or bundled JavaScript that needs readable source recovery, use
|
||||||
|
`recover_javascript_sources` with an absolute `path` and absent
|
||||||
|
`output_directory`. Supply related runtime/shared/lazy files in
|
||||||
|
`additional_paths` when advertised, then analyze the returned `analysis_input`
|
||||||
|
directory together. Each input retains its own snapshot, digest and byte-range
|
||||||
|
provenance; inputs and recovered code are never executed. Recovery requires a
|
||||||
|
caller-supplied Wakaru on Linux x64; see [the recovery guide](https://github.com/morluto/rea/blob/main/docs/javascript-recovery.md).
|
||||||
|
|
||||||
|
Use `analyze_javascript_application` directly on the operator-supplied ASAR or
|
||||||
|
extracted tree. When the question concerns known source paths and the connected
|
||||||
|
schema advertises `source_paths`, select exact inventoried paths such as
|
||||||
|
`["package.json", "main.js", "preload.js"]`. Include supporting manifests or
|
||||||
|
source maps explicitly; dependencies are not implicitly analyzed. REA retains
|
||||||
|
the complete artifact inventory and identity but reads source text and analyzes
|
||||||
|
only selected files. The result and summary record `source_selection`; files
|
||||||
|
outside scope and their relationships remain unknown, so partial application
|
||||||
|
coverage does not mean the selected source failed. Use repeated `--source-path`
|
||||||
|
on either static application CLI route. Omit the selection when the question
|
||||||
|
requires complete application analysis. `detail: "summary"` reduces delivery
|
||||||
|
and does not by itself reduce analysis work.
|
||||||
|
|
||||||
|
Exact `#alias` specifiers resolve through the importer's
|
||||||
|
enclosing package `imports` map to package-local files; nested `node_modules`
|
||||||
|
packages use their own map. Wildcard, recursive, and external-package import
|
||||||
|
targets stay unresolved with that limitation. When size is unknown or large and the connected schema advertises
|
||||||
|
`detail`, request `detail: "summary"`. This returns an `inspect_analysis_view`
|
||||||
|
Evidence record with a distinct ID and a `normalized_result.parent_evidence_id`
|
||||||
|
for the complete retained application analysis. Source-map contents are part of
|
||||||
|
that static analysis. Read findings, coverage, limitations and unknowns, then
|
||||||
|
follow a specific unanswered question. Older servers without `detail` return
|
||||||
|
the complete application Evidence inline when it fits.
|
||||||
|
|
||||||
|
When the connected schema advertises `max_heap_mb` and `analysis_timeout_ms`,
|
||||||
|
these select the isolated source analyzer's old-space heap and per-source
|
||||||
|
deadline. Defaults are 1024 MiB and 300000 ms. They do not change the MCP
|
||||||
|
process heap. A Bun-hosted REA does not enforce the heap choice; on Windows it
|
||||||
|
instead limits the analyzer's committed memory to that choice plus a 512 MiB
|
||||||
|
runtime reserve.
|
||||||
|
Resource-limited analyses preserve completed static facts and
|
||||||
|
report partial semantic coverage with specific unknown scopes; this does not
|
||||||
|
mean the source is malformed. Inspect those limits before retrying a source.
|
||||||
|
When expanded relationships exceed the parent's available memory, inspect the
|
||||||
|
file's modules item view for retained `static_analysis` and
|
||||||
|
`semantic_module_analysis`. Their facts remain available even when graph links
|
||||||
|
are unknown. Cumulative result exhaustion can stop analysis before every file
|
||||||
|
is examined; the inventory and remaining unknown scopes distinguish that case.
|
||||||
|
Timeout or cancellation after source analysis begins retains partial Evidence
|
||||||
|
in the same session. A returned `error.details.partial_observation` reference
|
||||||
|
can be supplied directly to `inspect_analysis_view`. If the SDK cancels locally, retrieve its recorded ID from
|
||||||
|
the Evidence bundle before inspecting the partial analysis.
|
||||||
|
|
||||||
|
## Read a module without repeating analysis
|
||||||
|
|
||||||
|
Use the actual returned parent ID, on the same connection, as `source.evidence_id`.
|
||||||
|
The following IDs are placeholders to replace with returned values. When the
|
||||||
|
module's node ID is not already known, page identities before selecting an item.
|
||||||
|
Pages return only node IDs, paths and roles; choose a useful page size and follow
|
||||||
|
`coverage.next_offset` when another page matters:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"source": {
|
||||||
|
"kind": "retained-evidence",
|
||||||
|
"evidence_id": "ev_ACTUAL_PARENT_ID"
|
||||||
|
},
|
||||||
|
"view": { "kind": "page", "collection": "modules", "offset": 0, "limit": 16 }
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Select the relevant page entry by its exact `node_id` and recorded role:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"source": {
|
||||||
|
"kind": "retained-evidence",
|
||||||
|
"evidence_id": "ev_ACTUAL_PARENT_ID"
|
||||||
|
},
|
||||||
|
"view": {
|
||||||
|
"kind": "item",
|
||||||
|
"collection": "modules",
|
||||||
|
"selector": { "node_id": "jag_node_ACTUAL_NODE_ID" }
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Module pages include asset, bundled and source module roles, so one path can
|
||||||
|
identify several entries. Use `selector.path` only when uniqueness is established;
|
||||||
|
the returned node ID avoids needing a complete inventory to prove uniqueness. On ambiguity,
|
||||||
|
select the matching node ID from the page or the error's candidates. Follow
|
||||||
|
`next_offset` when another page matters. An item exposes that module node's
|
||||||
|
recorded observations, identity, hashes, exports and source ranges; it does not
|
||||||
|
include every child syntax observation, related edge or original source file.
|
||||||
|
An absent item fact is not evidence of absence from the whole application.
|
||||||
|
|
||||||
|
## Trace only the remaining question
|
||||||
|
|
||||||
|
Use `trace_application_feature` on the parent application Evidence for one
|
||||||
|
literal node ID, route, string, API, IPC channel, module, or native export.
|
||||||
|
Select `incoming` for relationships leading to the seed, `outgoing` for those
|
||||||
|
leaving it, and `both` when the question needs both. Trace traversal includes
|
||||||
|
containment relationships, so even a narrow seed can expand many nodes; a
|
||||||
|
bidirectional trace can reach unrelated sibling modules. A module item or page
|
||||||
|
is preferable when its observations already answer the question. Do not treat
|
||||||
|
all reached nodes as participants in the feature.
|
||||||
|
|
||||||
|
Reuse retained parent Evidence when the server advertises it, or supply complete
|
||||||
|
Evidence inline. Include Hopper or Ghidra Evidence only when its artifact digest
|
||||||
|
matches exactly.
|
||||||
|
|
||||||
|
## Recover an oversized display
|
||||||
|
|
||||||
|
An oversized response reports `resource_constraint` and
|
||||||
|
`details.resource: "transport"`. Reuse
|
||||||
|
`details.reported_limits.evidence_reference` with `inspect_analysis_view` for a
|
||||||
|
summary, one module, or a stable page of module identities.
|
||||||
|
`export_evidence_bundle` writes the complete canonical session to a
|
||||||
|
caller-selected file. These workflows keep the original Evidence and coverage;
|
||||||
|
a broad follow-up can also exceed framing.
|
||||||
|
|
||||||
|
A client can truncate a successful result inside its text envelope without a
|
||||||
|
REA `resource_constraint`. Treat a truncation notice or incomplete JSON as a
|
||||||
|
display limitation; do not claim the full record was examined. Reuse the known
|
||||||
|
parent ID for smaller views, or export complete Evidence to a selected file
|
||||||
|
while the session remains open. If the parent ID was lost from the preview,
|
||||||
|
use the prior analysis summary or explicit ledger entries to recover it; do
|
||||||
|
not invent an ID or rerun analysis just to reproduce the same display.
|
||||||
|
|
||||||
|
BrowserWindow preferences, preload and contextBridge surfaces, IPC
|
||||||
|
registrations, utility processes, and native binding requests are static syntax
|
||||||
|
observations. Only a unique exact literal IPC channel match supports an inferred
|
||||||
|
pairing. Dynamic or ambiguous channels remain unresolved. A requested `.node`
|
||||||
|
member is not a verified native export. Never claim runtime reachability,
|
||||||
|
registration, defaults, or policy enforcement from static analysis.
|
||||||
|
|
||||||
|
For version comparison, analyze each version once, then call
|
||||||
|
`compare_application_versions`. Accept only its digest, source-map, structural
|
||||||
|
fingerprint, or non-module semantic matches. Module ordinals and minified names
|
||||||
|
are not persistent identity. Report added or removed only with complete
|
||||||
|
opposite-side coverage; otherwise report unknown.
|
||||||
|
|
||||||
|
When the question asks how one exact exported callable's returned object shape
|
||||||
|
changed, analyze each version once and then call
|
||||||
|
`compare_javascript_export_shapes` with explicit module paths and export names.
|
||||||
|
Use the returned IDs on the same connection, or complete inline Evidence
|
||||||
|
records, from both analysis calls. Accept variant
|
||||||
|
pairing only through the tool's unique exact literal discriminant. Read
|
||||||
|
`property_inventories` and each change's `presence` before treating `unknown` as
|
||||||
|
"the name was not observed": inventories list observed property names even when
|
||||||
|
values stay unknown, with a `source_range` for each paired or unpaired variant.
|
||||||
|
Array holes and mutation-invalidated slots are not observed properties.
|
||||||
|
Complete parent coverage reports presence-only
|
||||||
|
`added`/`removed` independently of unresolved values. Cite the
|
||||||
|
comparison Evidence and report JSON Pointer changes; dynamic values, ambiguous
|
||||||
|
variants, and incomplete parent-property coverage stay unknown. This is static
|
||||||
|
inference, not runtime behavior. When runtime semantics are needed, run
|
||||||
|
behavioral probes against the relevant application versions and capture them
|
||||||
|
through the available browser, Electron, or process workflows.
|
||||||
|
|
||||||
|
## Reusing application Evidence
|
||||||
|
|
||||||
|
When advertised by the connected server, application trace and compare tools
|
||||||
|
accept complete inline Evidence or
|
||||||
|
`{"kind":"retained-evidence","evidence_id":"ev_<64 lowercase hex characters>"}`
|
||||||
|
for their application input (`application`, or `left`/`right`). `inspect_analysis_view`
|
||||||
|
uses the same retained-reference form in `source`, or portable inline Evidence,
|
||||||
|
to project a summary, module page, or one module with its recorded observations. This notation is
|
||||||
|
a template: replace it with the actual returned ID. Versions before 4.1.0 accept only full
|
||||||
|
inline Evidence. Use the exact ID
|
||||||
|
returned by the producer on the same MCP connection. Resolution does not run
|
||||||
|
analysis or select a provider; findings remain inline. Native observation
|
||||||
|
arrays still take full Evidence. `close_binary` clears retained references;
|
||||||
|
export a bundle before closing, or supply portable inline Evidence in another
|
||||||
|
connection. A missing reference includes its ID and recovery guidance.
|
||||||
@@ -0,0 +1,277 @@
|
|||||||
|
# Native, managed, and packaged artifacts
|
||||||
|
|
||||||
|
## Go build metadata
|
||||||
|
|
||||||
|
Use `inspect_go_binary` for an explicit local ELF, PE or thin Mach-O when the
|
||||||
|
question concerns the embedded compiler version, module/dependency versions,
|
||||||
|
local replacements or build settings. No `open_binary`, Go installation or
|
||||||
|
target execution is required. The CLI equivalent is `inspect-go-binary PATH`.
|
||||||
|
Preserve artifact SHA-256, original file ranges, framed module bytes and every
|
||||||
|
unparsed module-text line. A missing record is an unknown, not proof of a
|
||||||
|
non-Go binary; observed metadata does not authenticate its claims. Function,
|
||||||
|
source and type recovery remain a separate native-analysis question.
|
||||||
|
|
||||||
|
## Rust dependency metadata
|
||||||
|
|
||||||
|
Use `inspect_rust_binary` for an explicit local ELF, PE, or thin Mach-O when
|
||||||
|
the question concerns the cargo-auditable crate list embedded in `.dep-v0`
|
||||||
|
(Mach-O: `__DATA,.dep-v0`). No `open_binary`, Rust installation, or target
|
||||||
|
execution is required. The CLI equivalent is `inspect-rust-binary PATH`.
|
||||||
|
Preserve artifact SHA-256, package order, dependency indices, and the section
|
||||||
|
file range. A missing section is null metadata, not proof the binary has no
|
||||||
|
dependencies. An omitted package kind stays null. A rustc commit hash is
|
||||||
|
inferred from a read-only `/rustc/<40-hex>/` path and does not by itself
|
||||||
|
identify the compiler. See [Rust binaries](https://github.com/morluto/rea/blob/main/docs/rust-binaries.md).
|
||||||
|
|
||||||
|
## SQLite snapshots
|
||||||
|
|
||||||
|
Use `inspect_sqlite_database` with an explicit local database snapshot for its
|
||||||
|
schema and optional rows from one exact ordinary table. It requires Node.js
|
||||||
|
24.x >=24.15 or 26+ with the native `DatabaseSync.limits` API. It also consumes the
|
||||||
|
existing sibling `-wal`; retain both original digests when citing its result.
|
||||||
|
Default output is a compact inventory; a selected table expands only its own
|
||||||
|
schema and samples 20 rows. Select `columns` to avoid irrelevant or large cells,
|
||||||
|
and request `schema_scope: "database"` only for complete schema details.
|
||||||
|
Choose `row_limit` when a finite sample is useful and keep truncation and
|
||||||
|
unspecified row order explicit. Virtual tables, shadow tables and views are
|
||||||
|
schema facts, not row-read targets. REA inspects private copies and leaves
|
||||||
|
the source files untouched; obtain a coherent quiescent database/WAL snapshot
|
||||||
|
before inspection. See [SQLite snapshots](https://github.com/morluto/rea/blob/main/docs/sqlite-databases.md).
|
||||||
|
|
||||||
|
## Recorded Linux crashes
|
||||||
|
|
||||||
|
Use `inspect_recorded_crash` with an explicit Linux x86-64 ELF core path to
|
||||||
|
inspect historical thread registers, signals, raw notes and original file
|
||||||
|
ranges. It is independent of the active disassembler target. Source-bound
|
||||||
|
register values and note bytes are observations; missing notes, signal-thread
|
||||||
|
association and current executable/library identity remain unknown. PIDs are
|
||||||
|
historical metadata and never authorize live attach or control.
|
||||||
|
|
||||||
|
The optional `include_debugger_context` facet adds mapping candidates through
|
||||||
|
caller-supplied GDB/pwndbg in an owned core-only session. Display names do not
|
||||||
|
establish current file identity; zero reported flags leave permissions unknown.
|
||||||
|
Requested unavailable context fails with setup guidance. See
|
||||||
|
[recorded crashes](https://github.com/morluto/rea/blob/main/docs/recorded-crashes.md)
|
||||||
|
for exact upstream profiles, bounds and verification coverage.
|
||||||
|
|
||||||
|
## Offline ELF layout
|
||||||
|
|
||||||
|
Use `inspect_binary_layout` with an explicit local ELF path for file-backed
|
||||||
|
sections, symbols, relocations, linkage names, and static mitigation inferences
|
||||||
|
without opening a disassembler target. When that complete record is already
|
||||||
|
retained, call `inspect_analysis_view` for a summary, mitigations or linkage
|
||||||
|
facet, one section or symbol, or a stable page. Do not re-run the decoder to
|
||||||
|
read a single object.
|
||||||
|
|
||||||
|
## Offline WASM
|
||||||
|
|
||||||
|
Use `inspect_wasm_artifact` with caller-supplied WABT for selected local bytes.
|
||||||
|
For counts, validation and WAT identity, select `detail: "summary"` on the first
|
||||||
|
MCP call. The complete original Evidence stays retained; use
|
||||||
|
`normalized_result.parent_evidence_id` for exact exports or text pages. Omitted
|
||||||
|
or complete detail keeps the existing complete result.
|
||||||
|
For a completed result, use `inspect_analysis_view` with its reported retained
|
||||||
|
reference for a summary or `view: {kind: "wasm", facet: "exports", offset: 0, limit: 32}`.
|
||||||
|
Facets also include sections, imports, candidates, glue, WAT, headers, details
|
||||||
|
and tool profile. Text offsets count UTF-16 code units; follow `next_offset`.
|
||||||
|
The complete source remains retained after an oversized MCP reply. No target
|
||||||
|
execution or network acquisition is implied, and WAT is decoded representation.
|
||||||
|
|
||||||
|
## Native targets
|
||||||
|
|
||||||
|
After `open_binary`, use focused search, procedure, or function tools directly.
|
||||||
|
Use `binary_overview` when target metadata or inventory context helps answer the
|
||||||
|
question. Prefer literal search, names, decompilation, callers, callees, and
|
||||||
|
cross-references. Addresses and recovered pseudocode are analysis observations,
|
||||||
|
not original source. Provider unavailability and unsupported metadata remain
|
||||||
|
unknown rather than false.
|
||||||
|
|
||||||
|
For a completed `analyze_function` dossier, use `inspect_analysis_view` with
|
||||||
|
`view: {kind: "native", facet: "value_flow_operations", offset: 0, limit: 32}`
|
||||||
|
and the exact retained Evidence ID to read selected facts without reanalysis.
|
||||||
|
Native facets also include procedure, pseudocode, assembly, basic blocks,
|
||||||
|
comments, callers/callees, references, unresolved calls, referenced strings and
|
||||||
|
names, the native API record, and value-flow summaries. Pseudocode offsets and limits count UTF-16
|
||||||
|
code units; use the returned `next_offset` for continuation. Provider limitations
|
||||||
|
and unavailable facts remain explicit; the complete parent Evidence is retained.
|
||||||
|
|
||||||
|
`inspect_macho` on a large framework returns megabytes of imports and exports.
|
||||||
|
Select `detail: "summary"` for slice identity, UUID and per-collection counts,
|
||||||
|
then page rows with `view: {kind: "macho", facet: "exports", offset: 0, limit: 64}`
|
||||||
|
and `normalized_result.parent_evidence_id`. Facets are entrypoints,
|
||||||
|
architectures, build_metadata, load_commands, dependencies, imports, exports,
|
||||||
|
segments and provenance. `source_exhaustive: false` means unreturned symbols
|
||||||
|
may exist.
|
||||||
|
|
||||||
|
To see which functions or Objective-C methods a Mach-O actually calls in one
|
||||||
|
run, use `observe_native_calls` with explicit breakpoints and a bounded
|
||||||
|
`duration_ms`/`max_events`. It launches a new process under LLDB, so the target
|
||||||
|
runs and may change files or use the network. Hardened-runtime targets need the
|
||||||
|
`get-task-allow` entitlement.
|
||||||
|
|
||||||
|
Use `binary_session` with no arguments to check the open target, selected
|
||||||
|
provider, and alignment. Its default `result.tool_availability` carries a
|
||||||
|
complete inventory grouped by shared facts. Expand each group's `names` and
|
||||||
|
inherit the inventory-level client requirements unless a group overrides them;
|
||||||
|
availability, reasons, remediation, modes, and flags remain inline. The
|
||||||
|
`effects` and `annotations` arrays name true flags from fixed vocabularies, so an
|
||||||
|
omitted known flag is false. `tools/list` remains the canonical source for full
|
||||||
|
tool schemas when target or provider state changes.
|
||||||
|
|
||||||
|
Provider capability groups carry provider identity and ordered limitations.
|
||||||
|
Prepend each set's `shared_limitations` to a group's `limitations` to recover the
|
||||||
|
operation's full ordered list. Candidate capabilities describe possible
|
||||||
|
providers. Top-level session capabilities describe the current route, and
|
||||||
|
`analysis_provider_binding` identifies the selected provider.
|
||||||
|
|
||||||
|
## DOS MZ with Ghidra
|
||||||
|
|
||||||
|
For an admitted DOS MZ target, use `inspect_native_load_image` to check measured
|
||||||
|
loaded bytes, file mappings, relocations and the entry against the immutable
|
||||||
|
snapshot. Keep `mismatch` and `unsupported` explicit. Verified import covers the
|
||||||
|
reported static image, not runtime DOS or PC-98 hardware behavior.
|
||||||
|
|
||||||
|
For Ghidra decompilation, `procedure_pseudo_code` also accepts `procedure: "file-offset:0x..."`; CLI `rea decompile <path> --file-offset=0x... --provider ghidra` resolves the source byte offset internally. An unresolved 0x-prefixed numeric procedure selector also falls back to a unique file mapping. Existing symbols and analysis addresses win; multiple mappings fail as ambiguous. Preserve the returned file-offset and address locations and raw selection observations. ELF virtual addresses are distinct from file offsets; never assume an arbitrary offset plus image base is an analysis address.
|
||||||
|
|
||||||
|
Use `read_bytes` for initialized analysis memory and `address_to_file_offset` to
|
||||||
|
anchor one observed address to original file bytes. Loader fixups can change a
|
||||||
|
word; a source offset does not imply byte equality. Complete function body ranges
|
||||||
|
use inclusive ends and can contain gaps. Do not treat the enclosing span as code.
|
||||||
|
For packed targets, retain the original and separately derived artifact identities;
|
||||||
|
decompiling an unpacking stub does not recover the unpacked program.
|
||||||
|
|
||||||
|
When reading Objective-C dispatch metadata, distinguish class implementation
|
||||||
|
methods from protocol requirements: class methods report null requirement
|
||||||
|
flags, while decoded protocol declarations retain required and optional facts.
|
||||||
|
Property attributes remain raw name/value tokens; use the property's
|
||||||
|
`atomicity` field for the decoded `N` marker or the default atomic behavior.
|
||||||
|
Null class/meta flags, ivar counts, atomicity, or read-only values mean the
|
||||||
|
selected provider did not establish that fact. Symbol names alone do not prove
|
||||||
|
that a class is a root class or has no ivars.
|
||||||
|
|
||||||
|
## Managed PE/CLI
|
||||||
|
|
||||||
|
Start with `inspect_managed_artifact`. REA's canonical managed inspection is
|
||||||
|
execution-free: do not claim it loaded, reflected, executed, or resolved the
|
||||||
|
assembly. Keep managed/native boundaries and unavailable reconstruction facts
|
||||||
|
explicit. A bring-your-own reconstruction oracle is separate from the canonical
|
||||||
|
parser and must not become an implicit setup dependency.
|
||||||
|
|
||||||
|
For identity/classification questions, `inspect_managed_artifact` can explicitly
|
||||||
|
select `detail: "summary"` on the first MCP call. It retains complete metadata
|
||||||
|
and returns a linked overview with full classification/evidence, nullable
|
||||||
|
module/MVID, frameworks, metadata coverage/issues/limitations and returned-row
|
||||||
|
counts. Default complete requests remain unchanged. Read original rows with
|
||||||
|
`inspect_analysis_view`, source `normalized_result.parent_evidence_id`, and
|
||||||
|
`view: {kind: "managed", collection: "attributes", offset: 0, limit: 16}`.
|
||||||
|
Collections are `references`, `resources` and `attributes`. Paging does not
|
||||||
|
repeat parsing. Returned-row exhaustion
|
||||||
|
does not prove complete metadata or absence under partial/unavailable coverage;
|
||||||
|
preserve build-local tokens and their artifact/MVID scope.
|
||||||
|
|
||||||
|
`inspect_managed_members` always returns the assembly-wide `member_refs`, even
|
||||||
|
for one selected type. For questions about a selected type, select
|
||||||
|
`detail: "summary"` with `type_names`; it returns the selection (with unmatched
|
||||||
|
names), coverage and per-collection counts. Page rows with
|
||||||
|
`view: {kind: "managed-members", collection: "call_edges", offset: 0, limit: 64}`
|
||||||
|
over `types`, `exported_types`, `fields`, `methods`, `member_refs`, `call_edges`,
|
||||||
|
`field_accesses` or `user_strings`.
|
||||||
|
|
||||||
|
### .NET NativeAOT
|
||||||
|
|
||||||
|
NativeAOT binaries contain native machine code, so ordinary CIL decompilers
|
||||||
|
cannot recover the original method bodies. When managed metadata/CIL is absent,
|
||||||
|
classify that as a native-analysis route rather than claiming source recovery.
|
||||||
|
Open the native image with the selected deep provider and inspect functions,
|
||||||
|
strings, calls, and references; describe decompiler output as pseudocode and
|
||||||
|
inference.
|
||||||
|
|
||||||
|
NativeAOT images can be PE/COFF, ELF, or Mach-O executables and shared
|
||||||
|
libraries. Use file bytes and loader metadata rather than suffixes to identify
|
||||||
|
them. For packaged apps, inventory/extract with REA's artifact tools and retain
|
||||||
|
the exact contained image identity. PDB, ELF debug, or dSYM sidecars are
|
||||||
|
additional evidence only when the provider accepts and matches them.
|
||||||
|
|
||||||
|
REA has a built-in read-only snapshot parser for x64 PE targets with .NET 8 RTR
|
||||||
|
9.1 metadata. An optional headless Ghidra adapter adds database annotations and
|
||||||
|
broader metadata recovery on Linux; it requires an explicitly configured
|
||||||
|
NativeAOT JAR. These are separate routes. The built-in parser also runs on
|
||||||
|
Windows Ghidra P0; read frozen literals from its report, because
|
||||||
|
`search_strings` does not include them. See the
|
||||||
|
[NativeAOT guide](https://github.com/morluto/rea/blob/main/docs/ghidra-nativeaot.md)
|
||||||
|
for setup, supported layouts, and host restrictions. Preserve binary identity
|
||||||
|
and distinguish derived metadata from Ghidra database observations. Recovered
|
||||||
|
types and native pseudocode are not original C# source. Windows Ghidra P0 has
|
||||||
|
no database mutation authority.
|
||||||
|
|
||||||
|
## Packages and extraction
|
||||||
|
|
||||||
|
Use `inspect_artifact` for application bundles, archives, ZIP/APK/IPA/MSIX/AppX,
|
||||||
|
ASAR, or DMG inputs when the artifact graph and findings help answer the
|
||||||
|
question. It returns the complete artifact graph inline. Cite graph manifest
|
||||||
|
IDs when using them.
|
||||||
|
|
||||||
|
For an IPA or a macOS `.app`, ZIP, or DMG, pass the inventory Evidence to
|
||||||
|
`project_apple_application_graph`. It reports application roots and nested
|
||||||
|
bundles by path convention: app extensions, XPC services, frameworks, login
|
||||||
|
items, system and driver extensions, and plug-ins. It also lists privileged
|
||||||
|
helpers, launchd plists, symlinks, and each bundle's `info_plist_path` and
|
||||||
|
executable candidates. Roles are path conventions, not parsed plists; read the
|
||||||
|
listed plists with `inspect_plist`.
|
||||||
|
|
||||||
|
After `open_binary` on a `.app` or Mach-O, use `trace_dylib_resolution` to see
|
||||||
|
which file each `@rpath`, `@loader_path` and `@executable_path` load reaches for
|
||||||
|
every executable in the bundle. It also lists missing or weak loads and earlier
|
||||||
|
`@rpath` candidates that are absent. Narrow large bundles with `roots` or
|
||||||
|
`architecture`. System paths stay undetermined because the dyld shared cache
|
||||||
|
provides them.
|
||||||
|
|
||||||
|
Use `extract_artifact` when materialized files are needed. It extracts the active
|
||||||
|
target and accepts optional `integrity_policy`; see the [MCP contracts](https://github.com/morluto/rea/blob/main/docs/mcp-contracts.md).
|
||||||
|
It materializes all regular files into a fresh temporary directory chosen by
|
||||||
|
REA. Symlinks and encrypted entries are inventory facts, not extractable files.
|
||||||
|
The result reports the materialized directory; callers do not choose the
|
||||||
|
destination. No separate permission grant is needed.
|
||||||
|
|
||||||
|
Native DMG traversal automatically uses a read-only mount on supported macOS
|
||||||
|
hosts, with an owned temporary mount directory and cleanup. It needs no approval
|
||||||
|
flag. Unsupported hosts or mount failures remain explicit limitations; do not
|
||||||
|
claim child inventory when only root identity is available. Extraction is a
|
||||||
|
separate filesystem-writing operation.
|
||||||
|
|
||||||
|
For headerless DOS COM, explicitly open with `format: "dos-com"` (CLI
|
||||||
|
`--target-format dos-com`). Inspect the load image before trusting function
|
||||||
|
analysis: the entry is `0x10100`, file offset zero, with imposed real-mode segment
|
||||||
|
context. PSP/stack/device state remains unmodeled. See [DOS guide](https://github.com/morluto/rea/blob/main/docs/ghidra-dos.md).
|
||||||
|
|
||||||
|
For other headerless images (embedded firmware without ELF/Mach-O/PE/MZ
|
||||||
|
headers), open with `format: "raw-binary"`, `architecture` (`x86`, `x86_64`,
|
||||||
|
`arm`, `arm64`, or `6502`), and `entry_point` (`0x` hex). File offset 0 is mapped at
|
||||||
|
that address. Hopper and IDA refuse this interpretation; Ghidra uses
|
||||||
|
`BinaryLoader` with a little-endian generic language. Big-endian, Thumb-only,
|
||||||
|
and Cortex-M variants are unsupported. `6502` selects NMOS 6502; the entry and
|
||||||
|
complete file mapping must fit within `0x0000..0xffff`. 65C02, 65816, cartridge
|
||||||
|
containers, bank switching, and mapper semantics are unsupported. Windows
|
||||||
|
Ghidra P0 admits raw images only for `6502`. See [raw binary guide](https://github.com/morluto/rea/blob/main/docs/raw-binary.md).
|
||||||
|
|
||||||
|
### Function annotations in Ghidra
|
||||||
|
|
||||||
|
Use `annotate_native_function` for one function name and/or entry comments, with at least one explicit change. Review its annotation readback and refreshed dossier inline. Changes are atomic and session-scoped; empty comments clear them, omitted fields preserve them. Later MCP calls observe edits until close. CLI `annotate-native-function` returns the updated analysis before discarding the session. Original executable bytes are unchanged; edits invalidate immutable snapshots. Windows P0 does not admit database mutations. For naming only, `set_address_name` / `set_addresses_names` also work with Ghidra: they name function entries or data addresses (primary labels) and return compact per-address success booleans instead of a dossier.
|
||||||
|
|
||||||
|
## Offline PE resource inventory
|
||||||
|
|
||||||
|
Use `inspect_pe_resources` with an absolute `path`, or
|
||||||
|
`rea inspect-pe-resources ./selected.exe --json`, for portable PE32/PE32+
|
||||||
|
resource inspection without opening a native target. Preserve returned Evidence:
|
||||||
|
type/name/language IDs and UTF-16 names, original directory/data/payload ranges,
|
||||||
|
code pages, payload hashes and static icon-group references. Same-language icon
|
||||||
|
resolution is explicit; missing references and size mismatch remain visible.
|
||||||
|
Other payloads are opaque, and this operation does not decode images or simulate
|
||||||
|
Windows resource loading. Consult the budgets and supported tree profile in
|
||||||
|
[offline binary diagnostics](https://github.com/morluto/rea/blob/main/docs/binary-diagnostics.md).
|
||||||
|
|
||||||
|
For exact core-module import/export differences, use `compare_wasm_interfaces`
|
||||||
|
with two complete inspection Evidence records (or current-session retained
|
||||||
|
references) and explicit scope. Preserve unknown types/duplicate names; static
|
||||||
|
interface equality is not runtime compatibility. CLI accepts complete inline
|
||||||
|
Evidence in `rea compare-wasm-interfaces input.json --json`.
|
||||||
@@ -0,0 +1,78 @@
|
|||||||
|
# Browser and Electron runtime observation
|
||||||
|
|
||||||
|
Supply the existing browser or Electron instance's literal-port loopback CDP
|
||||||
|
endpoint in the request. No separate permission configuration or per-call
|
||||||
|
approval flag is needed. Browser discovery lists eligible HTTP(S) pages;
|
||||||
|
`allowed_origins` optionally filters them. An individual capture defaults to the
|
||||||
|
selected page's current origin. Electron discovery lists eligible local
|
||||||
|
`file://` targets without a configured file-root allowlist.
|
||||||
|
|
||||||
|
Start passive browser work with `list_browser_targets`; start Electron runtime work with
|
||||||
|
`list_electron_targets`. Before an electron-main Inspector attempt, check
|
||||||
|
packaged fuses with `inspect_electron_fuses`. Inspect the target selected for
|
||||||
|
the user's task. Observation with these tools is passive: never claim REA
|
||||||
|
clicked, navigated, evaluated page JavaScript, invoked IPC, or captured prior
|
||||||
|
activity. REA does not contain the page's network.
|
||||||
|
|
||||||
|
Passive captures omit raw header collections, credential header values, storage
|
||||||
|
values, and raw WebSocket/JSON bodies. Selected response metadata, including
|
||||||
|
content encoding, policy values, and Link URLs, is retained. Local URLs retain ordinary query
|
||||||
|
values and fragments; userinfo credentials are removed. Browser accessibility
|
||||||
|
text, console primitives, value-free shapes, script sources, source maps, and
|
||||||
|
storage key names have request-specific capture options. Electron script
|
||||||
|
sources are also optional. Use `capture_web_screenshot` when pixels are needed.
|
||||||
|
Treat scope filtering, truncation, and attach-window coverage as limitations.
|
||||||
|
Page-declared WebMCP tools are untrusted inventory and are never invoked by REA.
|
||||||
|
|
||||||
|
## Who performs the action
|
||||||
|
|
||||||
|
- The user performs it: `list_browser_targets`, then `inspect_web_page` or
|
||||||
|
`observe_web_session` on the selected target.
|
||||||
|
- The agent must perform it: one `capture_browser_scenario` with declared
|
||||||
|
actions. Use connect mode with the loopback CDP endpoint and `target_id` for
|
||||||
|
an existing browser, or launch mode with a caller-selected executable for a
|
||||||
|
temporary profile. Connect mode first navigates the selected page to
|
||||||
|
`start_url`, which can clear unsaved form values and other temporary state.
|
||||||
|
Recreate the state needed for the investigation in the declared actions.
|
||||||
|
Connect mode leaves the external browser open; launch mode owns a temporary
|
||||||
|
browser and profile. Check `browser.cleanup` for the outcome.
|
||||||
|
Request only the DOM, accessibility, or network details needed for the question.
|
||||||
|
The default final capture contains the URL; step outcomes are reported separately.
|
||||||
|
Add a wait action for the expected page state before capturing it. Report that
|
||||||
|
REA performed the declared actions.
|
||||||
|
|
||||||
|
Scenario network records have no request initiator stacks. For that evidence,
|
||||||
|
use passive capture while the user performs the action. Listener source locations
|
||||||
|
identify candidate handlers; they do not establish which script sent a particular
|
||||||
|
request. Avoid overlapping passive capture and scenario actions on the same target.
|
||||||
|
|
||||||
|
Focused follow-up tools:
|
||||||
|
|
||||||
|
- `observe_web_execution`: execution coverage during a window; it resets
|
||||||
|
counters and temporarily disables optimization.
|
||||||
|
- `inspect_web_event_listeners`: source locations for listeners registered
|
||||||
|
directly on the first CSS match, without dispatching an event.
|
||||||
|
- `compare_web_captures`: two normalized passive captures or recorded scenarios.
|
||||||
|
- `discover_webmcp_tools`: inspect page-declared WebMCP inventory; never invoke
|
||||||
|
the discovered tools.
|
||||||
|
|
||||||
|
Use `reconcile_javascript_runtime` only after static application Evidence and
|
||||||
|
passive browser/Electron Evidence exist. Prefer captured-source digest identity;
|
||||||
|
report path/digest disagreement as a mismatch and preserve ambiguity. Explicit
|
||||||
|
path mappings are inference inputs and never broaden filesystem or CDP authority.
|
||||||
|
A bundle observed at runtime does not prove every contained module executed.
|
||||||
|
|
||||||
|
## Fiddler Everywhere traffic debugging
|
||||||
|
|
||||||
|
For large saved captures, request `detail: "summary"`, then page retained Evidence
|
||||||
|
with `inspect_analysis_view` and `view: {kind: "capture", detail: "preview", offset: 0, limit: 20}`.
|
||||||
|
Select complete record pages only for needed headers, metadata or payloads; views
|
||||||
|
read the historical parent without repeating capture decoding.
|
||||||
|
|
||||||
|
Inspect native `.saz` snapshots with `inspect_web_network_capture` and
|
||||||
|
`format: "saz"`; encrypted archives are unsupported. For live
|
||||||
|
traffic analysis, connect Everywhere's separate MCP server and use its
|
||||||
|
advertised session tools with an explicit `sessionsSource` (`LiveTraffic` or
|
||||||
|
`AgentCalls`). Preserve existing sessions and filters when inspecting a
|
||||||
|
recorded run. See the [capture and MCP guide](https://github.com/morluto/rea/blob/main/docs/web-network-captures.md)
|
||||||
|
for the workflow and Telerik's public setup and traffic-debugging skills.
|
||||||
+9
-8
@@ -7,6 +7,9 @@
|
|||||||
}:
|
}:
|
||||||
let
|
let
|
||||||
common = (import ../common/home.nix) { inherit pkgs; };
|
common = (import ../common/home.nix) { inherit pkgs; };
|
||||||
|
dots = "${config.home.homeDirectory}/.config/dotfiles";
|
||||||
|
# Symlink into the repo instead of /nix/store, so the target stays writable.
|
||||||
|
link = rel: { source = config.lib.file.mkOutOfStoreSymlink "${dots}/${rel}"; };
|
||||||
overwrite = {
|
overwrite = {
|
||||||
home.username = host.username;
|
home.username = host.username;
|
||||||
home.homeDirectory = "/Users/${host.username}";
|
home.homeDirectory = "/Users/${host.username}";
|
||||||
@@ -21,15 +24,13 @@ let
|
|||||||
|
|
||||||
home = {
|
home = {
|
||||||
|
|
||||||
activation.zedConfig = lib.hm.dag.entryAfter [ "writeBoundary" ] ''
|
|
||||||
mkdir -p ~/.config
|
|
||||||
if [ ! -L ~/.config/zed ]; then
|
|
||||||
rm -rf ~/.config/zed
|
|
||||||
ln -sf ~/.config/dotfiles/secrets/zed ~/.config/zed
|
|
||||||
fi
|
|
||||||
'';
|
|
||||||
|
|
||||||
file = {
|
file = {
|
||||||
|
# Writable symlinks into the repo
|
||||||
|
".config/zed" = link "secrets/zed";
|
||||||
|
".agents" = link "files/agents";
|
||||||
|
".config/opencode/AGENTS.md" = link "secrets/opencode/AGENTS.md";
|
||||||
|
|
||||||
|
# Read Only
|
||||||
".config/ghostty/config".source = ../files/ghostty/config;
|
".config/ghostty/config".source = ../files/ghostty/config;
|
||||||
".gitconfig".source = ../files/git/gitconfig;
|
".gitconfig".source = ../files/git/gitconfig;
|
||||||
".gitignore_global".source = ../files/git/gitignore_global;
|
".gitignore_global".source = ../files/git/gitignore_global;
|
||||||
|
|||||||
@@ -1,27 +0,0 @@
|
|||||||
#!/bin/bash
|
|
||||||
|
|
||||||
# Create secrets directory if it doesn't exist
|
|
||||||
mkdir -p secrets/plist
|
|
||||||
|
|
||||||
# Array of app IDs to export
|
|
||||||
APP_IDS=(
|
|
||||||
"com.lwouis.alt-tab-macos"
|
|
||||||
"com.jordanbaird.Ice"
|
|
||||||
"com.apphousekitchen.aldente-pro.plist"
|
|
||||||
"com.lihaoyun6.QuickRecorder.plist"
|
|
||||||
)
|
|
||||||
|
|
||||||
# Export each plist
|
|
||||||
for APP_ID in "${APP_IDS[@]}"; do
|
|
||||||
echo "Exporting $APP_ID..."
|
|
||||||
defaults export "$APP_ID" - >"secrets/plist/$APP_ID.plist"
|
|
||||||
|
|
||||||
# Check if export was successful
|
|
||||||
if [ $? -eq 0 ]; then
|
|
||||||
echo "Successfully exported $APP_ID to secrets/$APP_ID.plist"
|
|
||||||
else
|
|
||||||
echo "Failed to export $APP_ID"
|
|
||||||
fi
|
|
||||||
done
|
|
||||||
|
|
||||||
echo "All exports completed!"
|
|
||||||
@@ -1,38 +0,0 @@
|
|||||||
#!/bin/bash
|
|
||||||
|
|
||||||
# Path to the plist directory
|
|
||||||
PLIST_DIR="secrets/plist"
|
|
||||||
|
|
||||||
# Check if the plist directory exists
|
|
||||||
if [ ! -d "$PLIST_DIR" ]; then
|
|
||||||
echo "Error: Directory $PLIST_DIR does not exist."
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
# Get all plist files in the directory
|
|
||||||
PLIST_FILES=("$PLIST_DIR"/*.plist)
|
|
||||||
|
|
||||||
# Check if there are any plist files
|
|
||||||
if [ ${#PLIST_FILES[@]} -eq 0 ] || [ "${PLIST_FILES[0]}" = "$PLIST_DIR/*.plist" ]; then
|
|
||||||
echo "No plist files found in $PLIST_DIR."
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
# Import each plist
|
|
||||||
for PLIST_PATH in "${PLIST_FILES[@]}"; do
|
|
||||||
# Extract app ID from filename (remove path and .plist extension)
|
|
||||||
FILENAME=$(basename "$PLIST_PATH")
|
|
||||||
APP_ID="${FILENAME%.plist}"
|
|
||||||
|
|
||||||
echo "Importing $APP_ID..."
|
|
||||||
cat "$PLIST_PATH" | defaults import "$APP_ID" -
|
|
||||||
|
|
||||||
# Check if import was successful
|
|
||||||
if [ $? -eq 0 ]; then
|
|
||||||
echo "Successfully imported $APP_ID from $PLIST_PATH"
|
|
||||||
else
|
|
||||||
echo "Failed to import $APP_ID"
|
|
||||||
fi
|
|
||||||
done
|
|
||||||
|
|
||||||
echo "All imports completed!"
|
|
||||||
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Reference in New Issue
Block a user