hokipoki

Original source / Raw SKILL.md

---
name: hokipoki
description: "Switch AI models without switching tabs using the HokiPoki CLI. Hop between Claude, Codex, and Gemini when one gets stuck. Use when the user wants to request help from a different AI model, hop to another AI, get a second opinion from another model, switch models, share AI subscriptions with teammates, or manage HokiPoki provider/listener mode. Triggers on: 'use codex/gemini for this', 'hop to another model', 'ask another AI', 'get a second opinion', 'switch models', 'hokipoki', 'listen for requests'."
---

# HokiPoki Skill

Route tasks to different AI CLIs (Claude, Codex, Gemini) via the HokiPoki P2P network. API keys never leave the provider's machine; only encrypted requests and results are exchanged.

## Prerequisites

HokiPoki CLI must be installed and authenticated:

```bash
npm install -g @next-halo/hokipoki-cli
hokipoki login
```

Verify with `hokipoki whoami`. If not installed, guide the user through setup.

## Requesting Help from Another AI

Send a task to a remote AI model. Always use `--json` for parseable output:

```bash
# Specific files
hokipoki request --tool claude --task "Fix the auth bug" --files src/auth.ts --json

# Entire directory
hokipoki request --tool codex --task "Add error handling" --dir src/services/ --json

# Whole project (respects .gitignore)
hokipoki request --tool gemini --task "Review for security issues" --all --json

# Route to a team workspace
hokipoki request --tool claude --task "Optimize queries" --files src/db.ts --workspace my-team --json

# Skip auto-apply (just save the patch)
hokipoki request --tool codex --task "Refactor module" --dir src/ --no-auto-apply --json
```

Tool selection: if the user doesn't specify a tool, ask which model to use or omit `--tool` to let HokiPoki choose.

### Patch Auto-Apply

Patches auto-apply when the target directory is a git repo with committed files. If auto-apply fails, inform the user and suggest:

```bash
git init && git add . && git commit -m "initial"
```

## Provider Mode (Sharing Your AI)

Register and listen for incoming requests:

```bash
# Register as a provider (one-time)
hokipoki register --as-provider --tools claude codex gemini

# Start listening
hokipoki listen --tools claude codex
```

Tasks execute in isolated Docker containers (read-only filesystem, tmpfs workspace, auto-cleanup). Docker must be running.

## Status & Account

```bash
hokipoki whoami      # Current user info
hokipoki status      # Account, workspaces, history
hokipoki dashboard   # Open web dashboard in browser
```

## When to Suggest Hopping

- User is stuck on a problem after multiple attempts
- User asks for a different approach or fresh perspective
- Task involves a domain where another model excels (e.g., Codex for boilerplate, Gemini for large-context analysis)
- User explicitly asks to try another AI

## Full Command Reference

See [references/commands.md](references/commands.md) for all CLI options, auth token locations, and advanced usage.


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/commands.md

```markdown
# HokiPoki CLI Command Reference

## Authentication

| Command | Description |
|---|---|
| `hokipoki login` | Authenticate (opens browser) |
| `hokipoki logout` | Remove local auth |
| `hokipoki whoami` | Show current user |

## Request (Requester)

```
hokipoki request --tool <tool> --task "<description>" [options]
```

| Option | Description |
|---|---|
| `--tool <tool>` | AI tool: `claude`, `codex`, `gemini` |
| `--task <task>` | Task description |
| `--files <files...>` | Specific files to include |
| `--dir <dirs...>` | Directories to include recursively |
| `--all` | Include entire repo (respects .gitignore) |
| `--workspace <id>` | Route to specific team workspace |
| `--no-auto-apply` | Save patch without applying |
| `--json` | JSON output for programmatic use |
| `--interactive` | Interactive mode (human terminal only, NOT for agent use) |

## Provider

```bash
# Register (one-time)
hokipoki register --as-provider --tools claude codex gemini

# Listen for requests
hokipoki listen --tools claude codex
```

## Status

```bash
hokipoki status      # Account info, workspaces, history
hokipoki dashboard   # Open web dashboard
```

## Shell Completion

```bash
hokipoki completion --install   # One-time setup
exec $SHELL                     # Restart shell
```

## Token Locations

| Tool | Auth Command | Token Location |
|---|---|---|
| Claude | `claude setup-token` | `~/.hokipoki/` |
| Codex | `codex login` | `~/.codex/auth.json` |
| Gemini | `gemini` | `~/.gemini/oauth_creds.json` |

Auto-refresh: `hokipoki listen` auto-triggers re-auth if a token is expired.

## Codex Sandbox Fix

Codex blocks `.git/` writes by default. Add to `~/.codex/config.toml`:

```toml
[sandbox_workspace_write]
writable_roots = [".git"]
```

## Security Model

- Encrypted P2P connections
- LUKS-encrypted Docker containers
- Ephemeral git servers with one-time tokens
- No code retention after task completion
- Container memory auto-wiped after each task
- API keys never leave the provider's machine

```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### _meta.json

```json
{
  "owner": "budjoskop",
  "slug": "hokipoki",
  "displayName": "HokiPoki",
  "latest": {
    "version": "1.0.0",
    "publishedAt": 1769426690320,
    "commit": "https://github.com/clawdbot/skills/commit/a09672d0c7cb99a0d56102ab265fb9bb54811179"
  },
  "history": []
}

```