acp-background-runs
Route requests for ACP or external coding agents such as Codex, Claude Code, Gemini CLI, and OpenCode into non-blocking OpenClaw background ACP runs instead of executing synchronously in the current chat. Use when a user wants to hand coding work to an external agent and expects the current conversation to continue without waiting. Triggers: "ACP", "Codex", "Claude Code", "Gemini CLI", "OpenCode", "background run", "background task".
Install via CLI (Recommended)
clawhub install openclaw/skills/skills/ambition0802/acp-background-runsWhat This Skill Does
The acp-background-runs skill enables OpenClaw to offload heavy coding tasks and external agent requests to a non-blocking background runtime. Instead of stalling the current chat session while a coding agent (such as Codex, Claude Code, or Gemini CLI) processes complex code changes or project-wide refactors, this skill allows the user to continue interacting with OpenClaw seamlessly. It serves as a sophisticated controller that interfaces with the sessions_spawn utility, ensuring that background tasks are initialized with appropriate timeouts, working directories, and execution modes based on the user's specific intent.
Installation
To integrate this skill into your OpenClaw environment, execute the following command in your terminal:
clawhub install openclaw/skills/skills/ambition0802/acp-background-runs
Ensure that your environment has the necessary permissions to spawn background processes and that the target agents (e.g., ACP, Gemini CLI) are properly configured in your agent manifest.
Use Cases
- Project Refactoring: When you need a deep codebase analysis or a series of edits that would normally block your chat window for several minutes.
- Background Debugging: Initiating test runs or static analysis that you want to trigger now but review later.
- Contextual Coding: Running an agent to generate boilerplate code or documentation while you continue to research or design in the primary chat.
- Long-running Builds/Reports: Handing off tasks that involve iterative code generation or system testing where the user expects an asynchronous result notification upon completion.
Example Prompts
- "ACP, please run a full project scan on ~/projects/my-app and refactor the auth module in the background."
- "Use Claude Code to generate the unit tests for the current directory and notify me when the background run completes."
- "OpenCode: analyze the memory usage in this repository. Keep it as a background task; I want to keep working here."
Tips & Limitations
- Timeout Selection: Always choose a
runTimeoutSecondsthat matches the scale of the task. Do not default to zero unless you want an indefinite process. Use 600s for general coding and 1800s for intensive refactors. - Path Resolution: Always provide absolute paths for
cwdto prevent environment ambiguity. The skill performs best when paths are fully resolved before spawning. - Avoid Blocking: This skill is designed to prevent blocking the UI. If you find yourself needing to interact with the output in real-time, consider if a synchronous
subagentcall is actually more appropriate, though this sacrifices the non-blocking benefits. - Fallback Awareness: If the primary ACP runtime is unavailable, the skill defaults to
subagent. Always check the system notification to see which runtime was utilized so you can manage your credentials appropriately.
Metadata
Not sure this is the right skill?
Describe what you want to build — we'll match you to the best skill from 16,000+ options.
Find the right skillPaste this into your clawhub.json to enable this plugin.
{
"plugins": {
"official-ambition0802-acp-background-runs": {
"enabled": true,
"auto_update": true
}
}
}Tags(AI)
Flags: file-read, file-write, code-execution, external-api