Agent Registration
Relevant source files
The following files were used as context for generating this wiki page:
Agent Registration enables Scoutline to integrate with local AI agent environments. It deploys Scoutline rules and research capabilities ("skills") to the configuration directories of supported tools like Claude, Codex, and Copilot. This integration allows agents to use Scoutline for web research, archived lookups, and site crawls.
The system uses a registry to detect installed agent tools and employs specialized mutation engines to modify tool configuration files without destroying user edits. It maintains a lifecycle through versioned stamps to handle lazy refreshes and clean uninstallation via a reversal process.
Sources: packages/scoutline/tests/agent-registration.test.js:34-44, packages/scoutline/src/commands/init.ts:86-93
Architecture and Components
The architecture consists of three layers: a data-driven registry for detection, a deployment module for orchestrating file system operations, and mutation engines for granular file editing.
Tool Registry
The registry defines the supported agents and the specific paths for their rules and skills. It performs detection using directory-existence probes in the user's home directory.
| Agent ID | Detection Directory | Rules Mechanism |
|---|---|---|
claude | ~/.claude | Line insert in CLAUDE.md |
codex | ~/.codex | Marker block in AGENTS.md |
gemini | ~/.gemini | Line insert in GEMINI.md |
copilot | ~/.copilot | Dedicated instructions file |
opencode | ~/.config/opencode | JSON array in opencode.json |
qwen | ~/.qwen | Marker block in QWEN.md |
cursor | ~/.cursor | Detection-only (Unsupported) |
Sources: packages/scoutline/tests/agent-registration.test.js:64-106, packages/scoutline/tests/agent-registration-deploy.test.js:46-56
Mutation Engines
Scoutline modifies shared configuration files using three primary engine classes. These engines are idempotent, meaning repeated runs do not duplicate content.
- Line Insert Engine: Adds a pointer line (e.g.,
@rules/scoutline.md) to a list. It prefers splicing the line under existing similar rules but falls back to the end of the file. - Marker Block Engine: Injects a version-stamped block of text between Scoutline-specific HTML comments (
<!-- scoutline:start -->). This engine can create new files or augment existing ones. - JSON Array Engine: Appends the path to the Scoutline skill into a specific configuration array within a JSON file.
Sources: packages/scoutline/tests/agent-registration.test.js:133-143, packages/scoutline/tests/agent-registration.test.js:218-228, packages/scoutline/src/lib/agent-registration/deploy.ts:114-124
Registration Process
The registration occurs during the scoutline init wizard. The system detects tools and prompts the user for confirmation before performing any modifications.
The flowchart shows the sequential steps from tool detection through file backup to writing the final registration stamp.
Sources: packages/scoutline/src/commands/init.ts:400-435, packages/scoutline/src/lib/agent-registration/deploy.ts:128-142
Stamp and Lifecycle Management
Scoutline maintains a stamp file at <configRoot>/agent-registration.json. This file tracks the Scoutline version, the list of registered tools, and a SHA-256 hash of the rule text.
Lazy Refresh Logic
Every Scoutline CLI run invokes a lazy check. The system refreshes registered tools only if it detects drift in the Scoutline version or the rule text content.
- Version Drift: Triggers a re-copy of the skill tree.
- Text Drift: Triggers a rewrite of rule files and marker regions.
- Failures: Reported as non-fatal stderr notices. A partial failure keeps the stamp in a "drifted" state so the next run retries the failing tool.
Sources: packages/scoutline/src/lib/agent-registration/deploy.ts:24-34, packages/scoutline/src/lib/agent-registration/deploy.ts:176-218
Redaction and Redundancy
The registration logic preserves foreign directory modes to support group/shared installs. It also ensures that Scoutline-authored marker blocks do not interfere with user-authored blocks using the same marker names by strictly matching Scoutline-specific inner content.
Sources: packages/scoutline/tests/agent-registration-deploy.test.js:220-230, packages/scoutline/tests/agent-registration-init.test.js:965-975
Unregistration (Reversal)
Users can reverse all modifications by running scoutline init --unregister. The reversal logic performs a disk scan based on the registry.
The sequence diagram illustrates the unregistration flow, emphasizing the removal of Scoutline artifacts while preserving user-edited content.
Sources: packages/scoutline/src/lib/agent-registration/deploy.ts:228-268, packages/scoutline/tests/agent-registration-init.test.js:840-880
Disaster Recovery Backups
On the first mutation of a shared file, Scoutline creates a .scoutline-bak file. These backups are for disaster recovery only. The unregister process specifically avoids restoring from these backups to prevent losing user edits made since registration. Instead, it strips Scoutline-managed regions in place.
Sources: packages/scoutline/src/commands/init.ts:153-162, packages/scoutline/tests/agent-registration-docs.test.js:150-160
Configuration Data Model
The agentRules key is an additive object map in the main Scoutline configuration.
| Field | Type | Description |
|---|---|---|
agentRules | Record<string, boolean> | Map of tool IDs to opt-in status. |
agentRules.[toolId] | boolean | True if Scoutline is registered for this tool. |
Sources: packages/scoutline/src/commands/init.ts:861-875, packages/scoutline/tests/agent-registration-init.test.js:324-335
Agent Registration provides a robust mechanism for Scoutline to project its capabilities into various local development and AI environments. It prioritizes non-destructive modification and maintains integration health through a versioned lifecycle management system.