Groundcontrol

OpenCode plugin that enforces a provider allowlist, auto-exports sessions to Markdown, and adds
delegation/background tooling, AST-grep tools, slash commands, and workflow hooks.

Install

Use bun to install this package where you manage your opencode config (or globally if you prefer):

``bash
bun add @frenchtoastman/groundcontrol@latest
`

Then update your opencode config:

`json
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["@frenchtoastman/groundcontrol@latest"]
}
`

LLM-friendly install steps

1. Run bun add @frenchtoastman/groundcontrol@latest.
2. Open your opencode.json file.
3. Add "@frenchtoastman/groundcontrol@latest" to the plugin array.
4. Save the file and restart opencode.

Features

- Background agents: delegate tasks async and poll with background_output.
- Delegation tools: delegate_task, background_task, background_cancel.
- AST-grep tools: ast_grep_search, ast_grep_replace.
- Hooks: keyword detector, comment checker, session notifications, task resume hints, delegate retry, directory agents injector.
- Slash commands: /init-deep and /refactor (via the slashcommand tool).
- Directory agents injector: auto-injects AGENTS.md context when reading files.
- Session markdown export and provider allowlist enforcement.

Configuration

On first run, the plugin creates ~/.config/opencode/groundcontrol.json with defaults:

`json
{
"sessionLogPath": "~/.opencode/groundcontrol-sessions/",
"allowedProviders": [],
"features": {
"backgroundAgents": { "enabled": true, "pollIntervalMs": 2000, "maxPolls": 300 }
},
"tools": {
"astGrep": { "enabled": true, "maxMatches": 500, "maxOutputBytes": 1048576, "timeoutMs": 300000 },
"delegation": { "enabled": true }
},
"hooks": {
"keywordDetector": { "enabled": true },
"commentChecker": { "enabled": true, "customPrompt": "" },
"sessionNotification": { "enabled": true, "idleDelayMs": 10000, "sound": false },
"taskResumeInfo": { "enabled": true },
"delegateTaskRetry": { "enabled": true },
"directoryAgentsInjector": { "enabled": true, "maxLines": 200 }
},
"commands": {
"initDeep": { "enabled": true },
"refactor": { "enabled": true }
}
}
`

$3

Folder where Markdown exports are stored. Each session saves as .md.

$3

Optional allowlist to validate the enabled_providers list in your opencode.json. **Disabled
by default** (empty array). When populated, any provider in enabled_providers not in this list
blocks OpenCode startup with a clear error.

To enable provider enforcement, add the providers you want to allow:

`json
"allowedProviders": ["amazon-bedrock", "openai", "anthropic"]
`

Slash commands in opencode.json

Add slash commands to your opencode.json so they are available globally:

`json
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["@frenchtoastman/groundcontrol@latest"],
"commands": {
"init-deep": {
"description": "Generate hierarchical AGENTS.md files",
"tool": "slashcommand",
"args": { "command": "/init-deep" }
},
"refactor": {
"description": "Run structured refactor workflow",
"tool": "slashcommand",
"args": { "command": "/refactor $ARGUMENTS" }
}
}
}
`

Example agents

Create ~/.config/opencode/groundcontrol-agents.json (or merge into your main agent config):

`json
{
"agents": {
"background-runner": {
"description": "Launches background tasks and polls for results.",
"prompt": "Use delegate_task with run_in_background and poll with background_output.",
"tools": { "delegate_task": true, "background_output": true }
},
"ast-grepper": {
"description": "Uses AST-grep tools for large refactors.",
"prompt": "Use ast_grep_search and ast_grep_replace (dryRun first).",
"tools": { "ast_grep_search": true, "ast_grep_replace": true }
},
"init-deep": {
"description": "Generates hierarchical AGENTS.md instructions.",
"prompt": "Use slashcommand with /init-deep and follow the returned prompt.",
"tools": { "slashcommand": true }
},
"refactor": {
"description": "Runs the structured /refactor workflow.",
"prompt": "Use slashcommand with /refactor and follow the returned prompt.",
"tools": { "slashcommand": true }
}
}
}
``