Tools
Agent Knock Knock
By Control local Codex and Claude Code from OpenClaw, take over the same live tmux session, and run managed ACP tasks through ACPX with Cursor support.
Install
npm install -gREADME
# Agent Knock Knock (AKK)
[](https://www.npmjs.com/package/@scotthuang/agent-knock-knock)
[](https://github.com/scotthuang/agent-knock-knock/actions/workflows/ci.yml)
[](https://nodejs.org/)
[](https://github.com/scotthuang/agent-knock-knock/blob/main/LICENSE)
Agent Knock Knock lets you control local Codex and Claude Code from any configured OpenClaw channel, then take over the same live tmux session without losing context. For managed background work, Managed ACP (via ACPX) also supports Cursor.
**Local-first, with no hosted control plane or telemetry. tmux mode keeps the coding agent's existing permission settings; Managed ACP uses a separate background permission model.**
## See It in Action
[](docs/assets/akk-tmux-handoff-demo.mp4)
*OpenClaw asks Claude Code to write a file, waits for AKK to report completion, then hands the result to Codex. Both terminals remain available for direct human takeover. The demo uses the agents' existing permission settings; AKK does not switch them. Click the preview to watch in full quality.*
## Use Cases
**Delegate from anywhere.** Use any configured OpenClaw channel to hand work to a local coding agent wherever you are. AKK keeps the task running outside the chat, reports when the agent needs input or finishes, and lets you continue from chat or the shared terminal.
**Orchestrate specialist agents.** OpenClaw can coordinate agent handoffs: Claude Code can plan, Codex can implement, and Claude Code can review. In tmux mode, AKK can also automatically approve trusted permission requests under rules you define. At any point, you can take over the shared terminal, keep working yourself, then hand the same task back to OpenClaw—with context intact.
## Choose an Execution Mode
| Mode | Best for | Agents | Requires |
| --- | --- | --- | --- |
| **tmux bridge (recommended)** | Share one live CLI session. OpenClaw and a human can hand the task back and forth. | Codex, Claude Code | `tmux` |
| **Managed ACP** | Start background tasks with durable ACP state and callbacks. | Codex, Claude Code, Cursor | [ACPX](https://github.com/openclaw/acpx) |
Install either mode or both. tmux does not require ACPX. Cursor tmux control is [not yet supported](https://github.com/scotthuang/agent-knock-knock/issues/42). AKK can also discover, resume, or fork local Codex sessions; that is a Codex capability, not a third installation mode.
### Permission Boundaries
The two modes intentionally use different permission models:
- **tmux bridge:** AKK does not change the coding agent's configured permission mode. For supported prompts in an AKK-managed turn, disabled-by-default exact-command rules may auto-approve a trusted request; unmatched or uncertain requests stay manual.
- **Managed ACP:** AKK starts ACPX-backed agents with `--approve-all`; the tmux prompt inspection and exact-command `autoApprove` policy do not apply to this mode. Claude Code may still surface permission requests through ACPX, while some Codex sandbox-sensitive operations fail directly. Keep managed work inside an explicit workspace.
## Install
Core requirements:
- Node.js 22.14+ (Node.js 24 recommended; use a version supported by your OpenClaw release)
- [OpenClaw](https://docs.openclaw.ai/) Gateway and plugin API `2026.7.1-2` or newer
- At least one authenticated coding agent: Codex, Claude Code, or Cursor
### Install from ClawHub (recommended)
```bash
openclaw plugins install clawhub:@scotthuang/agent-knock-knock@beta
openclaw gateway restart
```
The explicit `@beta` selector follows the `0.3.0` prerelease channel. Remove it after the stable ClawHub release is available.
ClawHub installs the OpenClaw plugin, bundled AKK skill, and package-local relay CLI together. OpenClaw invokes that bundled CLI directly, but ClawHub does not add the `agent-knock-knock` command to your shell `PATH`. Do not run `install-openclaw` after a ClawHub install; that command belongs to the npm installation path below and would repeat the plugin setup.
If you also want standalone shell commands such as `agent-knock-knock doctor`, install the npm package globally without running `install-openclaw`:
```bash
npm install -g @scotthuang/agent-knock-knock@next
```
### Install from npm (beta)
```bash
npm install -g @scotthuang/agent-knock-knock@next
agent-knock-knock install-openclaw
```
The npm `next` dist-tag follows the same prerelease line. Remove `@next` after `0.3.0` becomes stable.
`install-openclaw` installs or updates the plugin, enables it, installs the AKK skill template, and restarts the OpenClaw Gateway. It is safe to rerun. Use `--skill-only` to skip plugin installation; add `--no-restart` to skip the automatic Gateway restart.
If OpenClaw runs from a local checkout or another nonstandard location, pass its CLI explicitly:
```bash
agent-knock-knock install-openclaw --openclaw-bin /path/to/openclaw/openclaw.mjs
```
AKK's agent tools are optional and require an explicit OpenClaw tool-policy opt-in. If you use the default `coding` profile and do not already have `tools.allow`, add AKK without replacing the profile:
```json5
{
tools: {
profile: "coding",
alsoAllow: ["agent-knock-knock"]
}
}
```
If your configuration already has a restrictive `tools.allow` list, add `"agent-knock-knock"` to that existing list instead. Do not set `allow` and `alsoAllow` at the same scope.
Choose one execution mode, or install both.
### Option A: tmux bridge (recommended)
Install tmux on macOS:
```bash
brew install tmux
```
Or on Debian/Ubuntu:
```bash
sudo apt-get install tmux
```
Then start a shared terminal session:
```bash
tmux new -s coding
```
Run `codex` or `claude` inside the tmux session. AKK will discover it automatically when OpenClaw and the coding agent run as the same user.
Claude tmux support requires no hooks and does not modify Claude Code settings. Hook-free completion monitoring is verified on Claude Code `2.1.198` and `2.1.218`; newer versions remain eligible when their interactive transcripts preserve the required identity and completion structure. Hookless auto-approval is deliberately narrower: approval evidence currently requires Claude Code `2.1.x` at `2.1.198` or later, and any other version falls back to manual handling.
### Option B: Managed ACP
Install ACPX:
```bash
npm install -g acpx
```
AKK uses ACPX to start managed Codex, Claude Code, or Cursor sessions from OpenClaw.
Finally, check which modes are ready if the global CLI is installed:
```bash
agent-knock-knock doctor
```
For a ClawHub-only installation, verify that OpenClaw loaded the packaged runtime:
```bash
openclaw plugins inspect agent-knock-knock --runtime
```
### Trust and Privacy
AKK is local-first. It has no hosted control plane or telemetry, does not modify coding-agent settings, and keeps its state, logs, terminal control, and approval decisions on your machine. Sensitive approval commands are never included in callbacks or AKK logs.
Your task content is still processed by OpenClaw and the coding-agent or model providers you configure. Use explicit workspaces, review agent permissions, and keep secrets out of custom callback commands.
## Quick Start
First merge this configuration into `~/.openclaw/openclaw.json`, setting `workspace` to the absolute path of the project agents may modify:
```json5
// ~/.openclaw/openclaw.json
{
tools: {
profile: "coding",
alsoAllow: ["agent-knock-knock"]
},
plugins: {
entries: {
"agent-knock-knock": {
config: {
defaultAgent: "codex",
workspace: "/absolute/path/to/project"
}
}
}
}
}
```
Restart the Gateway after changing the configuration:
```bash
openclaw gateway restart
```
For the recommended tmux mode, start an agent in tmux, then ask AKK to list and send to the discovered terminal:
```bash
tmux new -s claude-work
claude
```
```text
AKK list
AKK send <terminal-controlled-id>: inspect this repository and summarize it
AKK status <managed-conversation-id>
```
Attach to the same tmux session whenever you want to take over directly. Avoid typing while AKK is sending the same turn.
For Managed ACP, start a new task and use its conversation ID for follow-ups:
```text
AKK Codex: inspect this repository and summarize it
AKK status <conversation-id>
AKK send <conversation-id>: run the tests and fix any failures
```
For new ACP tasks, omitting the agent uses `defaultAgent`, falling back to Codex.
## How It Works
AKK keeps task state outside the chat channel, so OpenClaw can inspect and continue work even where threads are unavailable. OpenClaw remains the orchestrator; AKK supplies the ACP transport, tmux bridge, local state, and callbacks. See the [roadmap](https://github.com/scotthuang/agent-knock-knock/blob/main/ROADMAP.md) for planned work.
## Usage
Use conversational `AKK` prompts on any chat surface. Explicit agent names override the configured default:
```text
AKK Claude: review the latest commit
AKK Cursor: fix the flaky UI test
AKK describe <conversation-id>
AKK recover <conversation-id>
```
Surfaces with native commands use the same operations:
```text
/akk <task>
/akk list
/akk status <conversation-id>
/akk describe <conversation-id>
/akk send <conversation-id> <message>
/akk cancel <conversation-id>
/akk renew <conversation-id> [minutes]
/akk retry-callback <conversation-id>
/akk close <conversation-id> [reason]
```
Codex CLI sessions started outside AKK can also be resumed, opened in a ter
... (truncated)
tools
Comments
Sign in to leave a comment