runtrim 0.1.18 → 0.1.19

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +104 -76
  2. package/dist-cli/runtrim.cjs +869 -51
  3. package/dist-cli/runtrim.js +869 -51
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -1,76 +1,104 @@
1
- # RunTrim
2
-
3
- RunTrim is the control layer for AI coding agents.
4
-
5
- It gives Claude, Codex, Cursor, ChatGPT, and other agents project memory, scoped contracts, MCP guidance, approval flow, and finish verification before changes are accepted.
6
-
7
- Website: https://www.runtrim.com
8
-
9
- ## Install
10
-
11
- ```bash
12
- npm install -g runtrim
13
- ```
14
-
15
- ## Quickstart
16
-
17
- ```bash
18
- cd your-project
19
- runtrim start
20
- runtrim agent "Fix the homepage copy" --copy
21
- runtrim finish
22
- ```
23
-
24
- ## Primary flow
25
-
26
- 1. `runtrim start` analyzes the project and prepares local RunTrim memory and instructions.
27
- 2. `runtrim agent "task" --copy` creates a guarded run and handoff prompt for your coding agent.
28
- 3. Agent completes the task inside contract scope.
29
- 4. `runtrim finish` verifies scope and sensitive-file safety with a clear verdict: `PASS`, `WARN`, or `BLOCKED`.
30
-
31
- If scope needs to expand safely:
32
-
33
- ```bash
34
- runtrim approve "Allow <path or scope> for this run only"
35
- ```
36
-
37
- ## MCP (optional)
38
-
39
- ```bash
40
- runtrim mcp instructions
41
- runtrim mcp config --print
42
- runtrim mcp start
43
- ```
44
-
45
- MCP lets compatible agents use RunTrim tools like contract creation, path checks, approval suggestions, and finish guidance.
46
-
47
- ## Local-first trust model
48
-
49
- - Free CLI runs locally.
50
- - Source code stays local by default.
51
- - RunTrim does not read env file contents.
52
- - Ignored `.env.local` is warned and reported, not read.
53
- - Sensitive tracked/changed or unignored sensitive files still block finish.
54
-
55
- ## Plans and sync
56
-
57
- - Free: local control flow and local history.
58
- - Pro+: cloud sync and hosted dashboard history.
59
-
60
- ## Core commands
61
-
62
- ```bash
63
- runtrim start
64
- runtrim agent "Your task" --copy
65
- runtrim finish
66
- runtrim approve "Allow <scope> for this run only"
67
- runtrim status
68
- runtrim mcp instructions
69
- runtrim bridge status
70
- ```
71
-
72
- Advanced/lower-level command (still supported):
73
-
74
- ```bash
75
- runtrim go "Your task"
76
- ```
1
+ # RunTrim
2
+
3
+ RunTrim is the control layer for AI coding agents.
4
+
5
+ It gives Claude, Codex, Cursor, ChatGPT, and other agents project memory, scoped contracts, MCP guidance, approval flow, and finish verification before changes are accepted.
6
+
7
+ Website: https://www.runtrim.com
8
+
9
+ ## Install
10
+
11
+ ```bash
12
+ npm install -g runtrim
13
+ ```
14
+
15
+ ## Quickstart
16
+
17
+ ```bash
18
+ npm install -g runtrim
19
+ cd your-project
20
+ runtrim start
21
+ runtrim doctor
22
+ runtrim agent "Fix the homepage copy" --copy
23
+ runtrim finish
24
+ ```
25
+
26
+ ## Primary flow
27
+
28
+ 1. `runtrim start` analyzes the project and prepares local RunTrim memory and instructions.
29
+ 2. `runtrim agent "task" --copy` creates a guarded run and handoff prompt for your coding agent.
30
+ 3. Agent completes the task inside contract scope.
31
+ 4. `runtrim finish` verifies scope and sensitive-file safety with a clear verdict: `PASS`, `WARN`, or `BLOCKED`.
32
+
33
+ If scope needs to expand safely:
34
+
35
+ ```bash
36
+ runtrim approve "Allow <path or scope> for this run only"
37
+ ```
38
+
39
+ ## MCP (optional)
40
+
41
+ ```bash
42
+ runtrim mcp instructions
43
+ runtrim mcp config --print
44
+ runtrim mcp start
45
+ ```
46
+
47
+ MCP lets compatible agents use RunTrim tools like contract creation, path checks, approval suggestions, and finish guidance.
48
+ RunTrim does not silently modify global MCP config files. Use `runtrim mcp instructions` and `runtrim mcp config --print` to inspect snippets, and `runtrim doctor` to check readiness.
49
+
50
+ ## Local-first trust model
51
+
52
+ - Free CLI runs locally.
53
+ - Source code stays local by default.
54
+ - RunTrim does not read env file contents.
55
+ - Ignored `.env.local` is warned and reported, not read.
56
+ - Sensitive tracked/changed or unignored sensitive files still block finish.
57
+
58
+ ## Plans and sync
59
+
60
+ - Free: local control flow and local history.
61
+ - Pro+: cloud sync and hosted dashboard history.
62
+
63
+ ## Restore and rewind (local)
64
+
65
+ ```bash
66
+ runtrim restore last --preview
67
+ runtrim restore last --apply
68
+ ```
69
+
70
+ Restore points are local and source-safe. Apply happens locally through the CLI.
71
+
72
+ ## CI merge gate (GitHub Action v1)
73
+
74
+ RunTrim can run as a CLI-based PR check:
75
+
76
+ 1. Add `.github/workflows/runtrim.yml.example` to your repo as a workflow.
77
+ 2. Run `runtrim ci check --strict` on pull requests.
78
+ 3. Set branch protection to require the RunTrim check.
79
+
80
+ `runtrim ci check` returns `PASS`, `WARN`, or `BLOCKED`.
81
+ - `BLOCKED` exits non-zero and can prevent merge.
82
+ - `WARN` exits zero by default, or non-zero in `--strict` mode.
83
+
84
+ GitHub App and team policy sync are coming later.
85
+
86
+ ## Core commands
87
+
88
+ ```bash
89
+ runtrim start
90
+ runtrim doctor
91
+ runtrim agent "Your task" --copy
92
+ runtrim finish
93
+ runtrim approve "Allow <scope> for this run only"
94
+ runtrim status
95
+ runtrim mcp instructions
96
+ runtrim ci check
97
+ runtrim restore last --preview
98
+ ```
99
+
100
+ Legacy bridge compatibility (still supported):
101
+
102
+ ```bash
103
+ runtrim go "Your task"
104
+ ```