omnexx 0.0.0-stage → 0.1.0

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 (5) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +74 -2
  3. package/dist/cli.js +7152 -0
  4. package/dist/cli.js.map +1 -0
  5. package/package.json +66 -4
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 James Yaeger
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,75 @@
1
- # Temporary Holding Version
1
+ # omnexx
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ **Set a goal, walk away, come back to commits.**
4
+
5
+ Omnexx is a personal coding agent harness: one agent works on one huge task in one repo for about 24 hours with no one steering it. Your tests, typecheck and lint decide what's kept; every kept step is a small git commit on its own branch, and you get a report in the morning.
6
+
7
+ > **Alpha.** `0.1.0` is the first release: a personal tool, not a product. It uses your own Anthropic API key and spends your money. Verified against the real API: a one-task run (plan, fix, commit, report) cost $0.06; a single fix cycle cost $0.007 with a 90% cache-read share.
8
+
9
+ ## What it does
10
+
11
+ Omnexx is the loop around the model:
12
+
13
+ - **Fresh context every cycle.** Each cycle starts a new conversation built only from compact files on disk: the goal, a compact view of the plan, the last few progress entries, a capped lessons file and a codebase map. No transcript carries over.
14
+ - **Hierarchical, rolling-wave plan.** The planner writes milestones, then expands only the next one or two into small tasks. Nodes are never deleted, only parked with a reason.
15
+ - **Your commands are the judge.** Gates (tests, typecheck, lint, your own commands) run against a recorded baseline with a ratchet: no new failures, and the known-failure count can't go up. Anti-cheat rejects deleted tests, new `.skip`/`.only`/`@ts-ignore`/`eslint-disable`, snapshot rewrites and edits to protected files. A failed cycle is rolled back to the last green commit.
16
+ - **Stuck detection.** Repeated rejections, repeated failure signatures and A→B→A oscillation move a task up a strategy ladder (retry with evidence, then park). When nothing runnable is left, the run stops as `needs-human`.
17
+ - **Budgets.** USD, hours and cycle caps for the run, turn and token caps per cycle, and a pre-flight check before every model call so spend never overshoots by more than one turn. In the last 8% of the budget no new task starts.
18
+ - **Crash-safe.** Atomic state, a phase machine, a lock with boot-id staleness, `--detach`, and a systemd user unit or launchd agent that resumes runs after a reboot.
19
+ - **Checkpoints and a morning-after report.** Each finished milestone is tagged; `omnexx report` writes `REPORT.md` with the outcome, the plan tree, what changed, test deltas, where it struggled, spend, decisions it needs from you, and how to merge.
20
+ - **Your checkout is never touched.** Work happens in a git worktree on `omnexx/<runId>`; nothing is pushed unless you opt in.
21
+
22
+ Optional: an advisory **fast judge** (Nimble on Ollama, usually on your Mac over Tailscale) that suggests the next move and flags drift. It's off by default and can never override the gates. See [docs/judge.md](docs/judge.md).
23
+
24
+ ## Try it
25
+
26
+ ```bash
27
+ npm i -g omnexx
28
+ omnexx --version && omnexx doctor
29
+
30
+ cd <a repo with tests>
31
+ omnexx init # detects package manager and gates, asks before writing omnexx.toml
32
+ export ANTHROPIC_API_KEY=... # or: omnexx auth set anthropic
33
+ omnexx run --plan-only "Port src/legacy to strict TypeScript"
34
+ omnexx run --detach --budget 5 --hours 2 "Port src/legacy to strict TypeScript"
35
+ omnexx status && omnexx logs -f
36
+ omnexx report # in the morning
37
+ ```
38
+
39
+ Requires Node 22+, git and (recommended) ripgrep.
40
+
41
+ ## Commands
42
+
43
+ | Command | |
44
+ | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
45
+ | `omnexx init [--yes]` | Detect gates, write `omnexx.toml` |
46
+ | `omnexx run "<goal>"` | Plan, then cycle. `--goal-file`, `--detach`, `--budget`, `--hours`, `--gate`, `--model-worker`, `--push branch`, `--from`, `--plan-only`, `--i-know-there-are-no-checks` |
47
+ | `omnexx status [runId] [--json]` | Phase, task, progress, spend, heartbeat |
48
+ | `omnexx logs [runId] [-f] [--events\|--progress\|--cmd <id>]` | Human view of the event log |
49
+ | `omnexx plan [runId] [--edit]` | Show the plan, or edit `goal.md` (picked up next cycle) |
50
+ | `omnexx pause\|resume\|stop [runId] [--now]` | Control a run; `resume` also restarts a crashed supervisor |
51
+ | `omnexx resume --all` | What the service runs at boot |
52
+ | `omnexx runs` · `diff [--since <milestone>]` · `checkpoints` · `report` | Inspect results |
53
+ | `omnexx service install\|uninstall\|status [--dry-run]` | systemd user unit (Linux) or launchd agent (macOS) |
54
+ | `omnexx doctor [--offline] [--json]` | Environment checks; never prints your key |
55
+ | `omnexx auth set\|clear anthropic` | Store the key in a 0600 file |
56
+
57
+ Exit codes: `0` finished, `2` needs a human, `3` budget stop, `4` stopped by you, `1` error.
58
+
59
+ ## What does not work yet
60
+
61
+ Planned for M3 and later, and not in this build:
62
+
63
+ - Docker sandbox (`sandbox = "docker"` fails with "not implemented"). Host mode's limits are in [docs/safety.md](docs/safety.md).
64
+ - Model routing (planner/worker/cheap per turn), in-cycle compaction and tool-result clearing, flaky-test handling, the rolling daily spend cap (`max_usd_per_day` is accepted but not enforced), in-cycle stuck signals.
65
+ - Ladder rungs 2–4 (escalate model, re-plan a task, different approach). The judge's `split_task` and `switch_to_strong_model` options are logged but can't be acted on yet.
66
+ - Real worker adapters (Aider, OpenCode, Cline, Pi, Hermes, OpenHands, Claude Code). The interface, lifecycle and safety checks exist and are tested with a fake worker; enabling a worker fails with "adapter not available until M3". See [docs/workers.md](docs/workers.md).
67
+ - OpenAI-compatible providers, `open_pr`, the benchmark harness, npm publishing.
68
+
69
+ ## Docs
70
+
71
+ [Architecture](docs/architecture.md) · [Config](docs/config.md) · [Safety](docs/safety.md) · [Judge](docs/judge.md) · [Workers](docs/workers.md) · [VPS quickstart](docs/deploy-vps.md) · [Decisions](docs/DECISIONS.md) · [Plan](docs/PLAN.md)
72
+
73
+ ## License
74
+
75
+ MIT © 2026 James Yaeger