1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
|
Constrain agents to read files only through vr — enforcement comes from
harness config; AGENTS.md is navigation guidance only, never the constraint.
── files here ──────────────────────────────────────────────────────────────
claude-settings.json project install: <repo>/.claude/settings.json
(hook path uses $CLAUDE_PROJECT_DIR)
claude-headless-settings.json no-install variant for `claude -p --settings`
(hook path is absolute into this dir)
vr-only-guard.sh PreToolUse hook: blocks cat/rg/sed/... and
jj/git content reads; its error message points
the agent at `vr -doc`, so agents converge
even with zero instructions
vr-only.rules codex execpolicy rules (allow vr, forbid readers)
AGENTS.md how-to-navigate-with-vr guidance for the repo
── one-time setup ──────────────────────────────────────────────────────────
put both on PATH: go build -o ~/.local/bin/vr . (repo root)
cd vrsite && go build -o ~/.local/bin/vrsite .
(vr is what agents call; vrsite is how you read the trace)
── running a constrained CLAUDE investigation ──────────────────────────────
From the target jj repo dir:
claude -p --settings <vr-repo>/constrain/claude-headless-settings.json \
--allowedTools 'Bash(vr)' 'Bash(vr:*)' \
< prompt.txt > report.md
(<vr-repo> is wherever this repo lives; the settings file's hook path is
absolute into this directory, so it must be spelled out in full)
- --allowedTools on the CLI is required headless: allow rules inside
settings are IGNORED until the workspace is trusted (deny rules and the
hook always apply). Interactive use instead: install claude-settings.json
+ hook into the repo's .claude/, open once, accept the trust dialog.
- put the prompt on stdin; a positional prompt after --allowedTools gets
eaten by the flag's list parsing.
── running a constrained CODEX investigation ───────────────────────────────
cp vr-only.rules ~/.codex/rules/ # activate (GLOBAL: constrains
# every codex session while there)
codex exec -s danger-full-access "$(cat prompt.txt)" > report.md
rm ~/.codex/rules/vr-only.rules # deactivate when done
- danger-full-access is required: workspace-write blocks jj metadata writes,
including the sidecar rewrite and `vr read`'s working-copy snapshot.
- enforcement is pre-exec by codex's execpolicy engine, even through
`zsh -lc` wrappers; validate rules with:
codex execpolicy check --rules vr-only.rules -- cat foo.txt
── shared trace + rendering ────────────────────────────────────────────────
- vr creates one anonymous sidecar change directly under jj's root() on the
first append. The repo-local alias vr_log names it; git.private-commits
protects it from accidental pushes. No path or environment setup exists.
- Multiple agents in the repo share that sidecar. Rewrites are serialized,
note ids are assigned under the same lock, and the project @ is untouched.
- The sidecar has no bookmark and is local-only. It does not survive a fresh
clone; include the jj repository in backups when the trace matters.
- In the prompt, tell the agent to leave pinned notes
(vr note -f FILE:START-END -t kind "...") — that is the payload.
- Read traces afterwards from one process. Bare `vrsite` scans below ~ at
startup and when Refresh is pressed, then offers every repo with a sidecar:
vrsite
Its explicit buttons can start an empty private sidecar in a discovered jj
repo or initialize colocated jj in a discovered Git repo. The project index
is only in memory; those two requested metadata changes are the only writes.
- To bypass the dashboard and serve one repository directly:
vrsite -repo <repo> -title "..."
or take a static copy to hand around (one change, no server features):
vrsite -repo <repo> -out site -title "..."
`vrsite -h` explains both, and what a log needs to be worth reading.
── known holes (accepted) ──────────────────────────────────────────────────
Scripting runtimes (python/node/perl) can still open files — uncomment their
rules in vr-only.rules / extend the hook to close, at the cost of breaking
legitimate scripts. Neither harness constrains its own non-shell internals
beyond what the deny rules cover. Codex's rules file is global-only; there is
no per-project rules mechanism (probed, none exists as of codex 0.145).
|
