BoxLite Agent Tooling

TL;DR

Shared skills, independent audits, and repository gates that help coding agents carry work from design through review across BoxLite repositories.

Get started · Add to a repository · Architecture · Contributing

Why use it?

A repository can tell an agent how to work. This toolkit also checks key actions against that workflow: editing, committing, pushing, publishing a PR, and reporting completion.

You want…	The toolkit provides…
Consistent engineering practices across repositories	Shared guidance installed into AGENTS.md, plus reusable skills
Evidence behind an agent's conclusions	Independent auditors for completion claims and commit/push readiness
Reviewable changes	Design-document checks, a user choice to bypass or split large PRs, and human review acknowledgments
Feedback after a push	A PR watcher for checks, reviews, comments, and merge conflicts
Repository-specific verification	A small profile declaring the checks each project needs

Built for Claude Code and Codex. Copilot has a marketplace entry and generic manifest, but installation on a real host remains untested.

How it works

flowchart LR
    A[Repository profile] --> B[Install shared tooling]
    B --> C[Host skills and hooks]
    B --> D[Git hooks]
    C --> E[Request independent audit]
    D --> E
    E --> F{Gate checks evidence}
    F -->|Valid| G[Continue]
    F -->|Missing or invalid| H[Resolve and recheck]

Loading

The host plugin supplies skills, auditors, and lifecycle hooks. The repository installer configures Git hooks and shared instructions. Both are needed for the complete workflow; installing a host plugin alone does not configure a repository.

An auditor produces evidence bound to the work it reviewed. Gates read that evidence. For example, changing the staged diff after an audit invalidates its commit approval and requires another audit.

These are local workflow checks, not a sandbox or a GitHub security boundary. Git audit gates activate in agent-marked environments; browser writes and other unsupported routes fall outside CLI checks. See enforcement boundaries.

Get started

Already in a configured repository? From its root, run:

./.agent-tooling/install.sh

You need Bash, Git, jq, Perl, and the CLI for your host. GitHub operations require authenticated gh; declared project checks may need additional tools. First installation needs network access.

Host	Activate after repository setup
Claude Code	Trust the repository and its bootstrap hooks. After installation, run /reload-plugins or start a new session.
Codex	Trust the project SessionStart hook, then restart or resume. After installation, start a new task and review plugin hooks with /hooks.
Copilot	Activation files are supplied; end-to-end installation is unverified.

The installer updates the managed guidance in AGENTS.md and the CLAUDE.md import. Review those changes before committing. Background refreshes leave committed instructions alone.

Add to a repository

A consumer is a Git repository that uses this toolkit. Clone this source repository to obtain the files below, then add them to your consumer. Merge settings and hooks where files already exist.

1. Declare the project

Create .agent-tooling/profile.json. Replace the example repository and test command with your own:

{
  "schemaVersion": 1,
  "profile": "my-project",
  "repository": "your-org/your-repo",
  "tooling": {
    "repository": "boxlite-ai/agent-tooling",
    "ref": "main"
  },
  "checks": [
    { "name": "tests", "command": "npm test" }
  ]
}

tooling.ref names a branch. checks must contain at least one named command. The declared repository must match origin when one exists; profiles contain configuration, never credentials.

Add these runtime paths to the consumer's .gitignore:

.agents/state/
.claude/.last-audit.json
.claude/.last-audit-handoff.json
.claude/.last-verdict.json
.claude/.pr-reviewed.json
.claude/.verdict-last-uuid
.claude/.verdict-decisions.log

2. Add installation and activation files

Paths in the first column are relative to this source checkout; destinations are relative to the consumer root.

Source	Consumer destination
Installer	.agent-tooling/install.sh
Codex marketplace	.agents/plugins/marketplace.json
Claude bootstrap script	.agent-tooling/claude-plugin-bootstrap.sh
Claude bootstrap settings	Merge into .claude/settings.json
Codex bootstrap script	.agent-tooling/codex-plugin-bootstrap.sh
Codex bootstrap hook	Merge into .codex/hooks.json
Copilot activation settings	Merge into .github/copilot/settings.json

The profile validator currently requires activation declarations for all three hosts, even if you use only one. Keep their marketplace refs aligned with tooling.ref. Use the canonical Git marketplace source from the templates; local clone registrations conflict across worktrees.

For existing Claude settings, use the supplied merge helper from this checkout, with consumer set to the destination repository:

consumer=/absolute/path/to/your-repo
jq -s -f templates/merge-claude-plugin-settings.jq \
  "$consumer/.claude/settings.json" templates/claude-plugin-bootstrap.json \
  > "$consumer/.claude/settings.json.new" &&
  mv "$consumer/.claude/settings.json.new" "$consumer/.claude/settings.json"

For a new settings file, copy the template directly. For existing Codex hooks, append the template's SessionStart entry while preserving unrelated hooks.

3. Install and activate

From the consumer root:

chmod +x .agent-tooling/install.sh \
  .agent-tooling/claude-plugin-bootstrap.sh \
  .agent-tooling/codex-plugin-bootstrap.sh
./.agent-tooling/install.sh
git config --worktree --get core.hooksPath

The hook path should point into the adopted tooling checkout. Setup assigns the worktree's core.hooksPath; inspect existing hook integration before adoption. Commit the consumer files and generated instructions, then activate your host as described above.

Work with the toolkit

Ask your agent to work normally. Hooks check supported actions as they happen and explain what is needed when a gate blocks progress.

Task	Entry point
Research and write a design before coding	Use boxlite-design-doc.
Implement, refactor, or review maintainability	boxlite-clean-code
Shorten a reply, document, or PR description	boxlite-writing
Explain a subsystem with a concrete example	“Use boxlite-examples to explain how this subsystem works.”
Draw a diagram grounded in source	boxlite-visualize
Highlight essential phrases while preserving meaning	boxlite-reading-highlights
Implement a Bash hook or gate	shell-engineering
Iterate on design-review findings	adversarial-iteration
Register a design before implementation	Design registration
Prepare a PR for human review	Author acknowledgment

Workflow and writing reminders reference boxlite-writing by name; the host loads its instructions. Try: "Use boxlite-writing to shorten this PR description."

After a push, the Git hook starts the PR watcher. Codex setup requests one ten-minute schedule per chat to keep watchers alive and report new events. Scheduled and foreground turns acknowledge handled events; empty scheduled reads produce no reply. Scheduled input rows remain visible. Pauses, mutes, and opt-outs remain in force. Claude uses Monitor; desktop alerts require separate host verification. See the watch lifecycle.

Monitoring intent and pending events survive execution-session replacement. From the watched worktree, register once with bash <plugin-root>/.agents/watch/pr-watch-session.sh --start --branch <branch> --pr <number>. Subsequent calls without --start return bounded pending events and reconcile the producer. Acknowledge reported event IDs with --ack <id>; use --cancel to stop. Recovery honors the original deadline. Full pending storage stops polling until drained; host and OS settings still control desktop notifications.

For unattended Claude runs, the network-recovery wrapper retries recorded transient failures within bounded budgets. It requires claude, jq, curl, the failure-recording hook, and a matching CLAUDE_PROJECT_DIR.

BoxLite Clean Code skill

Use boxlite-clean-code to connect concrete maintainability problems to small changes while preserving contracts, resource ownership, and repository conventions. Try: "Use boxlite-clean-code to review this module's error handling without editing it."

The plugin exposes the skill through its existing shared skills directory. For standalone sharing, copy the entire boxlite-clean-code directory into a skill location supported by your agent, including its references/ directory. The core keeps essential principles and verification guidance; the example index routes concrete coding concerns to focused addons. Load only the relevant topics. There are no helper scripts or plugin dependencies. Repository workflow rules remain in AGENTS.md; the skill supplies focused engineering guidance.

Reading highlights

Use boxlite-reading-highlights to select short source phrases across a text. It aims for five highlighted words per sentence, expanding when meaning requires it; an explicitly requested hard limit takes precedence. Selections preserve conditions and negation, with skip reasons when meaningful partial selection fails.

Try: “Use boxlite-reading-highlights on this article; return the selected phrases.” Plain-text selection needs no browser. Applying yellow highlights to a page uses the optional browser reference and verifies actual coverage and text preservation.

For long pages or multiple chapters, the skill prepares reviewed plans from one extraction and supports bounded text-only workers when authorized. Browser application checks live text and sentence fingerprints before applying ranges in batches. Cached plans can be reused after validation; refreshing clears temporary marks, and cache data does not automatically restore them.

Optional prompt reminders

For prompt-only reminders, copy rule-recency.sh and its Markdown companion to the consumer's .agent-tooling/ directory and use the Codex or Claude template. The host must discover boxlite-writing; the copied hook references its name without embedding its rules. The companion is read on each invocation; missing files remain best effort and do not block prompts. Edit the companion to change the reminder. Set consumer to the destination repository before running the recipe below.

Claude Code needs a merge, not a copy — .claude/settings.json also carries keys such as env, and overwriting it would drop them:

mkdir -p "$consumer/.claude"
if [ -f "$consumer/.claude/settings.json" ]; then
  jq -s '
    .[0] as $current | .[1] as $rules |
    ($current * $rules) |
    .hooks.UserPromptSubmit = (
      reduce (
        (($current.hooks.UserPromptSubmit // []) +
         ($rules.hooks.UserPromptSubmit // []))[]
      ) as $entry
        ([]; if index($entry) == null then . + [$entry] else . end)
    )
  ' "$consumer/.claude/settings.json" templates/claude-settings.json \
    > "$consumer/.claude/settings.json.new" &&
    mv "$consumer/.claude/settings.json.new" "$consumer/.claude/settings.json"
else
  cp templates/claude-settings.json "$consumer/.claude/settings.json"
fi

Updates and troubleshooting

Consumers follow the branch in tooling.ref. The installer validates a fetched revision before recording it as adopted; offline verification uses that recorded cache. Host plugins refresh separately, so an adopted Git-hook revision does not prove a running session has reloaded.

Need	Action
Refresh tooling and shared instructions	Run ./.agent-tooling/install.sh explicitly.
Inspect the adopted revision	Read agent-tooling/current under git rev-parse --git-common-dir; agent-tooling/history.log records adoptions.
Pause background polling	Set AGENT_TOOLING_REFRESH=0; AGENT_TOOLING_REFRESH_MINUTES controls its interval.
Freeze repository tooling	Put one full lowercase commit SHA in .agent-tooling/hold, then run the installer. Remove it and reinstall to resume following the branch.
Repair missing or stale Git hooks	Rerun the installer; it can repair from an existing valid cache offline.
Load newly installed host resources	Reload Claude plugins or start a new Codex task; check hook trust.
Resolve a blocked action	Follow the gate's diagnostic; architecture maps each gate to its evidence and recovery path.

A hold constrains repository tooling; it does not silently roll back host plugins. A mismatched host-plugin version fails bootstrap. Consumer installer and bootstrap scripts are committed copies: refresh them from templates/ when adopting fixes to those scripts.

Develop and contribute

Reusable implementation lives in plugins/boxlite-agent-tooling/. Consumer bootstrap files live in templates/. Start with the contributor guide and architecture map.

Directory guides: host hook wiring, hook scripts, audit gates and runners, Git hooks, and maintenance scripts.

Run these repository checks, then the focused tests for the area you changed:

bash plugins/boxlite-agent-tooling/scripts/check-writing-ownership.sh .
bash plugins/boxlite-agent-tooling/host-parity.test.sh
bash plugins/boxlite-agent-tooling/architecture.test.sh

The optional GitHub author-review workflow enforces acknowledgments on PRs. Adopt it separately using a reviewed, immutable tooling revision, then require Author reviewed the PR in branch rules. Never run PR-head code in that privileged workflow.

License

Apache 2.0.