Compare commits

...
21 Commits
Author SHA1 Message Date
cupcakearmy bc8bf41580 add kicad 2026-11-22 00:31:04 +01:00
cupcakearmy 1d2e23a964 update deps 2026-11-22 00:30:48 +01:00
cupcakearmy 3ea100a66a tembo memory 2026-11-21 22:34:26 +01:00
cupcakearmy be136568ef Merge pull request #19 from 1virgola5/main
tinycast settings
2026-11-17 10:42:22 +01:00
nicco ea8f1229c1 remove old config files 2026-11-17 10:27:52 +01:00
nicco 938b0c0d66 add tinycast config 2026-11-17 10:27:45 +01:00
cupcakearmy 609d3f569a Merge pull request #18 from 1virgola5/main
stuff
2026-11-16 19:13:32 +01:00
nicco 48606a2869 update flake 2026-11-16 13:57:40 +01:00
nicco 59118ef446 fix colima setup 2026-11-16 13:57:34 +01:00
nicco e56f08bf24 add colima 2026-11-16 13:48:19 +01:00
nicco 4bba5aa3b2 merge 2026-11-16 10:14:08 +01:00
cupcakearmy 78f42209bb clean command 2026-11-13 16:38:02 +01:00
cupcakearmy 7a4d555982 update 2026-11-13 16:22:22 +01:00
nicco e68af805bc chore: update 2026-11-12 10:36:07 +01:00
cupcakearmy 0c542cf80d Merge pull request #16 from 1virgola5/main
Link files and remove plist
2026-11-10 13:04:06 +01:00
nicco c03dcd08a8 chore: remove plist stuff 2026-11-10 13:01:40 +01:00
nicco c010980921 chore: use outofstoresymlink 2026-11-10 13:01:24 +01:00
cupcakearmy bcfccbdcb2 add crtui 2026-11-05 12:51:01 +01:00
cupcakearmy 17d3f5a8d7 update flake 2026-10-30 16:07:13 +01:00
cupcakearmy 310eccef03 cleanup 2026-10-26 15:15:34 +01:00
cupcakearmy ae440685ab update flake 2026-10-26 15:13:55 +01:00
52 changed files with 4328 additions and 92 deletions
+1 -1
View File
@@ -7,7 +7,7 @@
# Utility
"macpacker"
"keycastr"
"abue-ammar/tinycast/tinycast"
"tinycast"
"ghostty"
"iina"
"cap"
-1
View File
@@ -84,7 +84,6 @@
g = "lazygit";
d = "lazydocker";
k = "kubectl";
colima-start = "colima start --cpu 4 --memory 8 --vm-type=vz --vz-rosetta";
};
};
+5 -2
View File
@@ -54,6 +54,9 @@
"com.apple.mouse.tapBehavior" = 1;
"com.apple.trackpad.scaling" = 0.875;
};
".GlobalPreferences" = {
"com.apple.mouse.scaling" = 0.5;
};
trackpad = {
Dragging = true;
Clicking = true;
@@ -87,7 +90,7 @@
homebrew = {
enable = true;
casks = (import ./cask.nix) ++ (lib.attrByPath [ "extras" "casks" ] [ ] host);
taps = [];
taps = [ ];
global = {
autoUpdate = true;
};
@@ -95,7 +98,7 @@
autoUpdate = true;
upgrade = true;
cleanup = "zap";
extraFlags = ["--force" ];
extraFlags = [ "--force" ];
};
};
}
+132
View File
@@ -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"
]
}
+8
View File
@@ -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
+365
View File
@@ -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}")
+67
View File
@@ -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.
+141
View File
@@ -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.
+103
View File
@@ -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.
+52
View File
@@ -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.
+120
View File
@@ -0,0 +1,120 @@
---
name: Tembo
description: Tembo is the project memory (elephant never forgets). Reads .tembo/notes.md facts and .tembo/log.md change log. Use at session start, after discovering a non-obvious project fact, or when flushing a session before pausing.
---
# Tembo
Project memory. Elephant never forgets, but keep it small:
```
.tembo/notes.md durable facts, read at session start
.tembo/log.md short chronological log of meaningful changes
```
Project root = `git rev-parse --show-toplevel`, else the current directory. If
there is no `.tembo/` yet, create it only when there is something worth
writing. Never write memory outside the project root.
## Budgets
Hard limits, enforced on every write:
| File | Limit | Overflow |
|---|---|---|
| `notes.md` | 40 lines | merge duplicates, then drop the least useful |
| `log.md` | 60 lines | drop oldest |
If you cannot fit a fact, it is not worth keeping.
## Format
One line per entry, newest last, `- [YYYY-MM-DD] tag: text`. Tags: `hardware`,
`build`, `cmd`, `api`, `gotcha`.
`notes.md`:
```markdown
# Tembo memory
<!-- Durable, non-obvious facts. Max 40 lines. One per line. -->
- [2026-11-21] gotcha: KiCad 10 pin-header footprints put pad 1 at the origin, not the centre.
- [2026-11-21] cmd: KiCad python bindings only run under the bundled 3.9 interpreter.
```
`log.md`:
```markdown
# Tembo log
<!-- One line per meaningful change. Max 60 lines. Newest last. -->
- [2026-11-21] Routed the carrier, DRC 0/0, exported gerbers.
```
## Read
At the start of work in a project with `.tembo/`:
1. Read `notes.md` in full.
2. Read the last ~20 lines of `log.md` for recent context.
Do not announce that you read them. Use them silently.
## Write
Append a `notes.md` line when a fact passes this test:
> Would this have saved 10 minutes if I had known it at the start?
Good: non-obvious tool behaviour, hardware/board quirks, commands that are not
in the README, decisions with a reason, traps.
Bad, do not write:
- anything obvious from the code, `git log`, README or AGENTS.md
- secrets, tokens, personal data, customer data
- code blocks, stack traces, file dumps, long URLs
- "created X" unless the *why* or a non-obvious constraint matters
- plans, TODOs, speculation
Append a `log.md` line when a meaningful unit of work is done: feature landed,
bug root-caused, board routed, dependency swapped. Not every file edit.
Never rewrite or reorder existing entries. Pruning to budget is the only edit
allowed.
## Remember (`/tembo <fact>`)
When invoked with an argument, treat it as a fact to keep:
1. Read both files.
2. Rewrite the argument into one line: `- [YYYY-MM-DD] tag: text`.
3. Pick the closest tag; write it as stated, do not invent context.
4. Dedupe against existing lines; append.
5. Prune to budget. Confirm in one short line.
If the argument is too vague to be useful later, ask once for the missing
detail instead of guessing.
## Flush (`/tembo` with no argument)
Run this before pausing or ending a session.
1. Review the session: what was discovered, what changed, what was verified.
2. Read both files.
3. Pick 0-5 facts that pass the test above and are not already recorded.
4. Pick 0-4 log lines for meaningful changes.
5. Dedupe against existing lines; merge near-duplicates.
6. Append, prune to budget, keep one blank line after the HTML comment.
7. Report two lines: facts added, log lines added. If nothing qualified, say
`tembo: nothing worth keeping` and write nothing.
Do not ask for confirmation. Do not paste file contents back; a short summary
is enough.
## Safety
- Never store secrets or credentials.
- Never delete `.tembo/` or another author's facts wholesale.
- If `.tembo/` is gitignored, still follow the same format; it is just local.
+288
View File
@@ -0,0 +1,288 @@
# Number of CPUs to be allocated to the virtual machine.
# Default: 2
cpu: 4
# Size of the disk in GiB to be allocated to the virtual machine for container data.
# NOTE: value can only be increased after virtual machine has been created.
#
# Default: 100
disk: 100
# Size of the memory in GiB to be allocated to the virtual machine.
# Default: 2
memory: 8
# Architecture of the virtual machine (x86_64, aarch64, host).
#
# NOTE: value cannot be changed after virtual machine is created.
# Default: host
arch: host
# Container runtime to be used (docker, containerd).
#
# NOTE: value cannot be changed after virtual machine is created.
# Default: docker
runtime: docker
# AI model runner (docker, ramalama).
# Both require krunkit VM type for GPU access.
# docker: Uses Docker Model Runner.
# ramalama: Uses Ramalama.
#
# Default: docker
modelRunner: ""
# Set custom hostname for the virtual machine.
# Default: colima
# colima-profile_name for other profiles
hostname: colima
# Kubernetes configuration for the virtual machine.
kubernetes:
# Enable kubernetes.
# Default: false
enabled: false
# Kubernetes version to use.
# This needs to exactly match a k3s version https://github.com/k3s-io/k3s/releases
# Default: latest stable release
version: v1.33.3+k3s1
# Additional args to pass to k3s https://docs.k3s.io/cli/server
# Default: traefik is disabled
k3sArgs:
- --disable=traefik
# Kubernetes port to listen on
# A common port is 6443, though left unbound to ensure no port conflicts
# Default: pick random unbound port
port: 0
# Auto-activate on the Host for client access.
# Setting to true does the following on startup
# - sets as active Docker context (for Docker runtime).
# - sets as active Kubernetes context (if Kubernetes is enabled).
# - sets as active Incus remote (for Incus runtime).
# Default: true
autoActivate: true
# Network configurations for the virtual machine.
network:
# Assign reachable IP address to the virtual machine.
# NOTE: this is currently macOS only and ignored on Linux.
# Default: false
address: false
# Network mode for the virtual machine (shared, bridged).
# NOTE: this is currently macOS only and ignored on Linux.
# Default: shared
mode: shared
# Network interface to use for bridged mode.
# This is only used when mode is set to bridged.
# NOTE: this is currently macOS only and ignored on Linux.
# Default: en0
interface: en0
# Use the assigned IP address as the preferred route for the VM.
# Note: this only has an effect when `address` is set to true.
# Default: false
preferredRoute: false
# Custom DNS resolvers for the virtual machine.
#
# EXAMPLE
# dns: [8.8.8.8, 1.1.1.1]
#
# Default: []
dns: []
# DNS hostnames to resolve to custom targets using the internal resolver.
# This setting has no effect if a custom DNS resolver list is supplied above.
# It does not configure the /etc/hosts files of any machine or container.
# The value can be an IP address or another host.
#
# EXAMPLE
# dnsHosts:
# example.com: 1.2.3.4
dnsHosts:
host.docker.internal: host.lima.internal
# Replicate host IP addresses in the VM. This enables port forwarding to specific
# host IP addresses.
# e.g. `docker run --port 10.0.1.2:8080:8080 alpine` would only forward to the
# specified IP address.
#
# Default: false
hostAddresses: false
# Custom gateway address for the virtual machine.
# The last octet needs to be 2.
#
# EXAMPLE
# gatewayAddress: 192.168.10.2
#
# Default: 192.168.5.2
gatewayAddress: null
# ===================================================================== #
# ADVANCED CONFIGURATION
# ===================================================================== #
# Forward the host's SSH agent to the virtual machine.
# Default: false
forwardAgent: false
# Docker daemon configuration that maps directly to daemon.json.
# https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-configuration-file.
# NOTE: some settings may affect Colima's ability to start docker. e.g. `hosts`.
#
# EXAMPLE - disable buildkit
# docker:
# features:
# buildkit: false
#
# EXAMPLE - add insecure registries
# docker:
# insecure-registries:
# - myregistry.com:5000
# - host.docker.internal:5000
#
# Colima default behaviour: buildkit enabled
# Default: {}
docker: {}
# Virtual Machine type (krunkit, qemu, vz)
# NOTE: this is macOS 13 only. For Linux and macOS <13.0, qemu is always used.
#
# vz is macOS virtualization framework and requires macOS 13.
# krunkit runs super‑light VMs on macOS/ARM64 with a focus on GPU access. It is experimental.
#
# NOTE: value cannot be changed after virtual machine is created.
# Default: qemu
vmType: vz
# Port forwarder for the virtual machine (ssh, grpc, none).
# ssh is more stable but supports only TCP.
# grpc supports both TCP and UDP, but is experimental.
# none disables port forwarding.
#
# Default: ssh
portForwarder: ssh
# Utilise rosetta for amd64 emulation (requires m1 mac and vmType `vz`)
# Default: false
rosetta: false
# Enable foreign architecture emulation via binfmt (e.g. amd64 on arm64, arm64 on amd64)
# Default: true
binfmt: true
# Enable nested virtualization for the virtual machine (requires m3 mac and vmType `vz`)
# Default: false
nestedVirtualization: false
# Volume mount driver for the virtual machine (virtiofs, 9p, sshfs).
#
# virtiofs is limited to macOS and vmType `vz`. It is the fastest of the options.
#
# 9p is the recommended and the most stable option for vmType `qemu`.
#
# sshfs is faster than 9p but the least reliable of the options (when there are lots
# of concurrent reads or writes).
#
# NOTE: value cannot be changed after virtual machine is created.
# Default: virtiofs (for vz), sshfs (for qemu)
mountType: virtiofs
# Propagate inotify file events to the VM.
# NOTE: this is experimental.
mountInotify: false
# The CPU type for the virtual machine (requires vmType `qemu`).
# Options available for host emulation can be checked with: `qemu-system-$(arch) -cpu help`.
# Instructions are also supported by appending to the cpu type e.g. "qemu64,+ssse3".
# Default: host
cpuType: host
# Custom provision scripts for the virtual machine.
# Provisioning scripts are executed on startup and therefore needs to be idempotent.
#
# EXAMPLE - script executed as root
# provision:
# - mode: system
# script: apt-get install htop vim
#
# EXAMPLE - script executed as user
# provision:
# - mode: user
# script: |
# [ -f ~/.provision ] && exit 0;
# echo provisioning as $USER...
# touch ~/.provision
#
# EXAMPLE - script executed after VM boot, before container runtimes start
# provision:
# - mode: after-boot
# script: echo "VM is up, containers not yet started"
#
# EXAMPLE - script executed after VM and container runtimes are ready
# provision:
# - mode: ready
# script: echo "everything is ready"
#
# Default: []
provision: []
# Modify ~/.ssh/config automatically to include a SSH config for the virtual machine.
# SSH config will still be generated in $COLIMA_HOME/ssh_config regardless.
# Default: true
sshConfig: true
# The port number for the SSH server for the virtual machine.
# When set to 0, a random available port is used.
#
# Default: 0
sshPort: 0
# Configure volume mounts for the virtual machine.
# Colima mounts user's home directory by default to provide a familiar
# user experience.
#
# EXAMPLE
# mounts:
# - location: ~/secrets
# writable: false
# - location: ~/projects
# writable: true
#
# Colima default behaviour: $HOME is mounted as writable.
# Default: []
mounts: []
# Specify a custom disk image for the virtual machine.
# When not specified, Colima downloads an appropriate disk image from Github at
# https://github.com/abiosoft/colima-core/releases.
# The file path to a custom disk image can be specified to override the behaviour.
#
# Default: ""
diskImage: ""
# Use the custom disk image even if it does NOT match a supported release image.
# WARNING: This bypasses validating the image and is a completely unsupported!
forceDiskImage: false
# Size of the disk in GiB for the root filesystem of the virtual machine.
# This value is ignored if no runtime is in use. i.e. `none` runtime.
# Default: 20
rootDisk: 20
# Environment variables for the virtual machine.
#
# EXAMPLE
# env:
# KEY: value
# ANOTHER_KEY: another value
#
# Default: {}
env: {}
+272
View File
@@ -0,0 +1,272 @@
{
"general": {
"launcherShortcut": "cmd+space",
"showInMenuBar": true,
"automaticallyCheckForUpdates": true,
"popToRootSeconds": 90,
"escapeKeyBehavior": "navigateBackOrClose",
"autoSwitchInputSource": null,
"supportReminders": false,
"language": "en"
},
"appearance": {
"theme": "system",
"animations": true,
"interfaceSize": "standard",
"compactMode": false,
"compactBarCommands": [
"command:clipboard-history",
"command:search-emoji",
"command:search-files",
"command:search-quicklinks"
],
"followCursorAcrossDisplays": true,
"dragToReposition": false
},
"hyperKey": {
"key": "none",
"includesShift": true,
"quickPress": "none",
"secureInputCompatibility": false
},
"calculator": {
"numberStyle": "system"
},
"search": {
"showsSuggestions": true,
"sensitivity": "medium"
},
"applications": {
"enabled": true,
"searchScopes": [
"/Applications",
"/Applications/Utilities",
"/System/Applications",
"/System/Applications/Utilities",
"/System/Library/CoreServices/Applications",
"/System/Volumes/Preboot/Cryptexes/App/System/Applications",
"/System/Library/CoreServices/Finder.app",
"~/Applications"
],
"apps": {
"ai.opencode.desktop": {
"shortcut": "option+4",
"alias": null,
"showInLauncher": true
},
"app.zen-browser.zen": {
"shortcut": "option+1",
"alias": null,
"showInLauncher": true
},
"com.mitchellh.ghostty": {
"shortcut": "option+3",
"alias": "t",
"showInLauncher": true
},
"com.spotify.client": {
"shortcut": "option+9",
"alias": null,
"showInLauncher": true
},
"com.tinyspeck.slackmacgap": {
"shortcut": "option+0",
"alias": null,
"showInLauncher": true
},
"dev.zed.Zed": {
"shortcut": "option+2",
"alias": null,
"showInLauncher": true
}
}
},
"systemSettings": {
"enabled": true,
"panes": {}
},
"systemActions": {
"enabled": true,
"actions": {}
},
"commands": {
"builtInEnabled": true,
"builtIn": {},
"enabled": false,
"showInLauncher": true
},
"quicklinks": {
"enabled": true,
"showInLauncher": true,
"opensNewWindow": false,
"passesSelectedText": false,
"confirmsBeforeDelete": true,
"commands": {}
},
"appleShortcuts": {
"enabled": false
},
"ai": {
"enabled": false,
"webSearch": false,
"choices": true,
"expandsReasoning": false,
"systemPrompt": "",
"systemPromptEnabled": true,
"retentionDays": "forever",
"opensTo": "recent",
"newChatAfterMinutes": 5,
"toolRounds": 25,
"commands": {}
},
"quickActions": {
"targetLanguage": "",
"commands": {}
},
"dictation": {
"mode": "toggle",
"shortcut": null,
"playsSounds": true,
"model": "redux",
"microphone": null,
"destination": "paste",
"adaptsCapitalization": true,
"liveInsertion": false,
"releaseAfterMinutes": 1,
"language": null
},
"fileSearch": {
"enabled": false,
"scopes": ["~"],
"ignorePatterns": [],
"removedDefaultPatterns": [],
"showInLauncher": false,
"commands": {}
},
"notes": {
"enabled": false,
"rendersMarkdown": true,
"showsFormattingBar": true,
"showsInMenuBar": false,
"folder": null,
"commands": {}
},
"snippets": {
"showInLauncher": true,
"folder": null,
"defaultAction": "paste",
"commands": {}
},
"navigation": {
"enabled": false,
"menuSearchShowsAppleMenu": false,
"menuSearchDisabledApps": [],
"commands": {}
},
"windowManagement": {
"enabled": true,
"showInLauncher": true,
"gap": 0,
"cycle": "off",
"wrapDisplays": true,
"keepProportions": true,
"layoutsShowInLauncher": true,
"roomsShowInLauncher": true,
"shortcuts": {
"left-half": null,
"right-half": null,
"top-half": null,
"bottom-half": null,
"top-left-quarter": null,
"top-right-quarter": null,
"bottom-left-quarter": null,
"bottom-right-quarter": null,
"first-three-fourths": null,
"last-three-fourths": null,
"first-third": null,
"center-third": null,
"last-third": null,
"first-two-thirds": null,
"last-two-thirds": null,
"maximize": null,
"almost-maximize": null,
"reasonable-size": null,
"maximize-height": null,
"maximize-width": null,
"center": null,
"center-half": null,
"center-two-thirds": null,
"make-larger": null,
"make-smaller": null,
"restore": null,
"move-left": null,
"move-right": null,
"move-up": null,
"move-down": null,
"move-to-left-edge": null,
"move-to-right-edge": null,
"move-to-top-edge": null,
"move-to-bottom-edge": null,
"next-display": null,
"previous-display": null,
"toggle-fullscreen": null,
"previous-space": null,
"next-space": null
},
"aliases": {},
"customSizes": [
{
"id": "34f8f38c-6694-4f1a-9ec6-2ff10d9bf257",
"name": "Middle Size",
"width": "1600pt",
"height": "1000pt",
"position": "center",
"offset": {
"x": 0,
"y": 0
},
"shortcut": null,
"alias": null
}
],
"layouts": [],
"rooms": [],
"commands": {}
},
"clipboard": {
"enabled": true,
"retentionDays": 90,
"defaultAction": "paste",
"disabledApps": ["com.apple.keychainaccess", "com.apple.Passwords"],
"commands": {
"clipboard-history": {
"shortcut": "cmd+h",
"alias": null,
"showInLauncher": true
}
}
},
"emoji": {
"skinTone": "none",
"gridColumns": 8,
"commands": {}
},
"calendar": {
"showInLauncher": true,
"launcherLimit": 5,
"span": "todayAndTomorrow",
"joinWindowMinutes": 5,
"autoJoinConfirms": true,
"autoJoinNamedProvidersOnly": false,
"meetingBrowser": null,
"menuBar": "disabled",
"menuBarUpcomingEvents": "today",
"menuBarLinkedEventsOnly": true,
"menuBarHidesWhenEmpty": false,
"hideCurrentEventAfterMinutes": "never",
"commands": {}
},
"extensions": {
"showInLauncher": true
}
}
Generated
+12 -12
View File
@@ -7,11 +7,11 @@
]
},
"locked": {
"lastModified": 1792085665,
"narHash": "sha256-X9iN67cdW9KqLuvbyyr9rdF4Zssk1uFHh1UC/GZH08s=",
"lastModified": 1795268568,
"narHash": "sha256-1RJm4DEu7YHJv94sjSY7sjqT+kHx/AUwmtUN4dtFBUo=",
"owner": "nix-community",
"repo": "home-manager",
"rev": "54ad640b81c5e9a32db1a29e7561fda628601117",
"rev": "6857c7f7c338ad181729c52071386b0d3afa24bc",
"type": "github"
},
"original": {
@@ -25,11 +25,11 @@
"nixpkgs": "nixpkgs"
},
"locked": {
"lastModified": 1792076306,
"narHash": "sha256-8jEHuNqlRw65knIzbcuCHt2vl2jv8/cLsFYTfK0d/v8=",
"lastModified": 1795272803,
"narHash": "sha256-v/AlZwJYPvjQ5to1dpQJb8nx5hmTUCVW+SMkL5nxxkM=",
"owner": "tw93",
"repo": "mole",
"rev": "0d92da5c855af23310cc1d19a6fb5a713c0bc2c8",
"rev": "5c2edd1a17880d3ace0ad0f158863f8b029a92a3",
"type": "github"
},
"original": {
@@ -46,11 +46,11 @@
]
},
"locked": {
"lastModified": 1786845137,
"narHash": "sha256-oQFip+v0luP8NIxJzmiW4Wu8bILsbFWom5l0zonl8hQ=",
"lastModified": 1795302518,
"narHash": "sha256-HJKykg05SUTzWyGpbkGeBuLxJJUYx713ZSu3780YW2Y=",
"owner": "LnL7",
"repo": "nix-darwin",
"rev": "4cff07de74b50e64bdd68cd4e722ab5b6b35ee48",
"rev": "bcf051043c8c6e6473eb44245ed81bca90856523",
"type": "github"
},
"original": {
@@ -77,11 +77,11 @@
},
"nixpkgs_2": {
"locked": {
"lastModified": 1791966044,
"narHash": "sha256-t1hT8UW97rFCWCJO7/pClvu0AhLN5V3uir2M0ic4w/Q=",
"lastModified": 1795249095,
"narHash": "sha256-8JDgyVvWUZg5m9hNlL8Ge9aT647ng3Ukc8NPMiKNTPQ=",
"owner": "NixOS",
"repo": "nixpkgs",
"rev": "319e4cebef10cbb636c6ea392137b52ad105336a",
"rev": "93a9ed0a866099a230ed5146a5bb7d16fd5c9b14",
"type": "github"
},
"original": {
+12 -9
View File
@@ -7,6 +7,9 @@
}:
let
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 = {
home.username = host.username;
home.homeDirectory = "/Users/${host.username}";
@@ -21,15 +24,15 @@ let
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 = {
# Writable symlinks into the repo
".config/zed" = link "secrets/zed";
".colima/_templates/default.yaml" = link "files/colima/colima.yaml";
".agents" = link "files/agents";
".config/opencode/AGENTS.md" = link "secrets/opencode/AGENTS.md";
".config/tinycast/settings.json" = link "files/tinycast/settings.json";
# Read Only
".config/ghostty/config".source = ../files/ghostty/config;
".gitconfig".source = ../files/git/gitconfig;
".gitignore_global".source = ../files/git/gitignore_global;
@@ -49,7 +52,7 @@ let
c = "pwd | pbcopy";
vai = "sudo darwin-rebuild switch --flake ~/.config/dotfiles#${host.hostName}";
clean = "nix-collect-garbage -d";
clean = "nix profile wipe-history && nix store gc && nix store optimise";
};
sessionVariables = {
+3
View File
@@ -11,6 +11,9 @@ with pkgs;
posting
opencode
# TUI
(callPackage ../pkgs/crtui.nix { })
# NVim
nvs
lua
+3 -2
View File
@@ -25,19 +25,20 @@
"freecad"
"blender"
"freelens"
"tailscale-app"
"kicad"
];
pkgs =
pkgs: with pkgs; [
docker-client
colima
docker-buildx
biome
infisical
ffmpeg
mkcert
codecrafters-cli
postgresql_18
yt-dlp
exiftool
];
};
}
+45
View File
@@ -0,0 +1,45 @@
{
lib,
stdenv,
fetchzip,
}:
let
version = "0.4.1";
plat = {
"aarch64-darwin" = "darwin_arm64";
"x86_64-darwin" = "darwin_amd64";
"aarch64-linux" = "linux_arm64";
"x86_64-linux" = "linux_amd64";
};
in
stdenv.mkDerivation {
pname = "crtui";
inherit version;
src = fetchzip {
url = "https://github.com/ksckaan1/crtui/releases/download/v${version}/crtui_${version}_${
plat.${stdenv.hostPlatform.system}
or (throw "crtui: unsupported platform ${stdenv.hostPlatform.system}")
}.tar.gz";
hash = "sha256-Rue9l2dZR8J6+XCV4HGOvYywklDa9jq4I6IUlhmtTF8=";
stripRoot = false; # tarball has no single top-level dir
};
# Prebuilt binary: skip fixup so llvm-strip does not invalidate the
# ad-hoc Mach-O signature macOS arm64 requires.
dontFixup = true;
installPhase = ''
runHook preInstall
install -Dm755 $src/crtui $out/bin/crtui
runHook postInstall
'';
meta = {
description = "Terminal-based container registry management tool";
homepage = "https://github.com/ksckaan1/crtui";
license = lib.licenses.mit;
mainProgram = "crtui";
platforms = builtins.attrNames plat;
};
}
-27
View File
@@ -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!"
-38
View File
@@ -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.