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 recognize harness environment markers and agent processes recorded by PreToolUse; 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
Write or shorten a reply, document, or PR description as structured output	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
Extract essential knowledge or a minimal working example	boxlite-distill
Implement a Bash hook or gate	shell-engineering
Iterate on design-review findings	adversarial-iteration
Register a design before implementation	Design registration
Prepare or revise a PR description	boxlite-pr-preparation
Acknowledge the current PR diff	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 report before acknowledging handled events. Empty scheduled reads emit no events; consumers omit routine status prose. Visible silence depends on the host and requires separate verification. 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."

For non-obvious algorithms, layouts, protocols, ownership, or concurrency, the skill directs agents to its comment guidance before implementation or review. That guidance teaches visual layouts, algorithm traces, and worked calculations. Try: "Implement this search and explain duplicate handling with a worked trace."

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.

Distill knowledge and implementations

Use boxlite-distill to reduce a topic or system to the core needed to understand or reproduce one behavior. It retains an element when removing it would break the explanation, a necessary condition, or that behavior. A whole-system request gets an overview of its major responsibilities and connections; selected deep dives do not replace that coverage. A requested implementation preserves one complete instance of the system's defining behavior. An explicitly requested subsystem stays narrow. For codebases, actual types or modules explain responsibilities, important state, interfaces, and collaboration, then map to the reduced example.

Try: "Use boxlite-distill to explain this module's core mechanism," or "Extract a minimal runnable example with boxlite-distill." The skill selects a knowledge guide, an implementation guide, or both, then returns the goal, essential core, demonstration, omissions, and verification. Code inputs can be explained without generating code; requested implementations are separate learning artifacts unless source modification was requested. Unavailable runtimes remain explicit verification gaps. Representations match the reader's background; unfamiliar syntax is explained. The main lesson retains essential roles, a causal example, run commands, and limits; deeper internals, layouts, encodings, and proof sit behind links. Coverage, fidelity, execution, reader sufficiency, and evidence completeness have separate results. Missing required checks prevent a complete verdict. The usage evaluation workflow keeps source fixtures, frozen artifacts, and evidence budgets outside the skill.

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. Startup/resume and Git lifecycle events share a 15-minute release check, even when the repository and host plugin have matching versions. The installer validates a fetched revision before adopting it; offline refresh keeps a valid recorded installation.

For example, repository tooling and the installed plugin can both be at 0.1.35 while the branch publishes 0.1.36. The next eligible startup adopts that release and reconciles the current host's plugin. Already loaded sessions still need a reload or a new task.

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 automatic release checks	Set AGENT_TOOLING_REFRESH=0; a mismatched host version then requires explicit repair. AGENT_TOOLING_REFRESH_MINUTES sets the interval (0–99999; zero checks every time).
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. Disabled plugins stay disabled; installing files does not grant hook trust.

Migrate existing consumers once

After 0.1.35 merges, run the existing installer, then replace all three .agent-tooling/*.sh files listed above with the released templates. Review and commit the consumer changes; merge customizations explicitly. Keep the older scripts for a hold pinned below 0.1.35.

The host scripts become loaders for the adopted package. The consumer installer delegates later adoptions to that package too, retaining its self-contained first-install fallback. Later updater fixes arrive with releases; automatic refresh leaves tracked scripts and guidance alone. A missing compatible runtime fails with migration instructions.

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.