Agent Integration

Overview

gosok’s CLI is designed for programmatic use by AI agents and scripts. An agent can create projects, spawn tabs, run commands, and receive results — all through the CLI.

Environment Variables

Each tab’s shell automatically receives:

Variable	Description
GOSOK_TAB_ID	The current tab’s ID
GOSOK_API_URL	The gosok server URL

Agent Workflow Example

# 1. Create a project
proj=$(gosok project create my-app --path /code/my-app | awk '{print $2}')

# 2. Create and start a tab
tab=$(gosok tab create $proj --name "test-runner" | awk '{print $2}')
gosok tab start $tab

# 3. Send a message to the tab
gosok msg send $tab "npm test"

# 4. Wait for a response
result=$(gosok msg wait --timeout 60s $tab)

# 5. Notify when done
gosok notify "Tests Complete" --body "$result" --flag

Messaging System

Tabs can communicate with each other using the msg subcommand:

Direct Messages

# From tab A, send to tab B
gosok msg send <tab-b-id> "build done"

Broadcast

# Send to all tabs
gosok msg send --all "DB migration complete"

Global Feed

# Post to the feed
gosok msg feed "v2.1 release ready"

# Read the feed
gosok msg feed

Inbox & Wait

# Read inbox
gosok msg inbox

# Block until a message arrives (or timeout)
gosok msg wait --timeout 30s

The msg wait command exits with code 0 on message received, 1 on timeout — making it easy to use in scripts and agent loops.

Reading Terminal Output

Use tab screen to programmatically read what’s on a tab’s terminal:

# Read last 24 lines (default)
gosok tab screen <tab-id>

# Read last 50 lines
gosok tab screen <tab-id> --lines 50

Writing to Terminal Input

Use tab write to send text to a tab’s terminal:

gosok tab write <tab-id> "npm test"

This appends a newline, so the command runs immediately.

Claude Code Plugin (Recommended)

The gosok repo ships a Claude Code plugin under integrations/claude/gosok/. Installing it gives Claude:

• A gosok-cli skill documenting the gosok CLI surface and common workflows, so Claude reaches for the right command when you ask it to “open a tab”, “check that build”, or “ping the other session”.
• A Stop hook that pushes a gosok notify when Claude finishes a response.
• A Notification hook that pushes a gosok notify when Claude is waiting for input or permission.
• A SessionStart hook that injects the current gosok server state (project + tab counts) into Claude’s context.

Install from inside Claude Code — no clone needed:

/plugin marketplace add cookieshake/gosok-terminal
/plugin install gosok@gosok-terminal

The first command registers this repo as a Claude Code plugin marketplace; the second pulls the plugin from it. Update later with /plugin marketplace update gosok-terminal.

If you’ve cloned the repo locally and want to develop against the plugin, install it from the working tree instead:

/plugin install ./integrations/claude/gosok

All hooks silent-fail when gosok isn’t on PATH or the server is unreachable, so the plugin is safe to leave installed across machines. Each hook can be disabled individually via env vars (GOSOK_PLUGIN_NOTIFY_ON_STOP, GOSOK_PLUGIN_NOTIFY_ON_INPUT, GOSOK_PLUGIN_SESSION_CONTEXT — set any to 0 to opt out).

See the plugin’s own README for the full environment-variable reference and troubleshooting.

Claude Code Hooks (Manual)

If you don’t want the plugin — for example, to use just one of the hooks without the skill — Claude Code hooks can be wired by hand. Since gosok tabs set GOSOK_TAB_ID and GOSOK_API_URL in every shell, hook scripts can use the gosok CLI directly.

Add hooks to ~/.claude/settings.json or .claude/settings.json:

Notify When Claude Finishes

Send a gosok notification with tab flagging whenever Claude completes a response:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "gosok notify \"Claude done\" --body \"Waiting for input\" --flag"
          }
        ]
      }
    ]
  }
}

The --flag option turns the tab’s dot yellow in the sidebar, so you can spot which tabs need attention at a glance.

Broadcast Status to Other Tabs

Notify all other tabs when Claude starts or finishes working:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "gosok msg feed \"Claude finished in $(gosok tab list | grep $GOSOK_TAB_ID | awk '{print $2}')\""
          }
        ]
      }
    ]
  }
}

Open the notification center in gosok to see a live feed of all Claude activity across tabs.