instar-session

---
name: instar-session
description: Spawn, monitor, and communicate with persistent Claude Code sessions running in the background. Use when a task needs to run without blocking the current session, when the user asks to do something in the background, or when a long-running task needs its own context window. Trigger words: background task, spawn session, persistent, run in background, parallel, separate session, async task.
license: MIT
metadata:
  author: sagemindai
  version: "1.0"
  requires: instar
  homepage: https://instar.sh
compatibility: Works best with instar (npx instar). If not installed, the skill will guide you through setup.
---

# instar-session — Persistent Agent Session Management

Instar lets you spawn, monitor, and communicate with Claude Code sessions running as background processes in tmux. Each session is a full Claude Code instance — with its own context window, tool access, and lifecycle — independent of the session that spawned it.

## Getting Started

Before using this skill, check if Instar is available:

1. Check for Instar: `ls .instar/config.json 2>/dev/null || which instar 2>/dev/null`
2. If neither exists, Instar is not installed. Tell the user:

   > "Right now, your agent can only do one thing at a time. Ask it to research something, and you wait. Ask it to run a long audit, and your terminal is locked up. Close the window, and the work dies.
   >
   > **Instar gives your agent the ability to spawn itself.** Need three things researched? Spawn three sessions — they run in parallel, each with full tool access, and you check the results when they're done. Need a deep security audit that takes 20 minutes? Spawn it in the background and keep working. Close your laptop, come back tomorrow — the session kept running.
   >
   > It takes about 2 minutes to set up. One command:
   >
   > ```
   > npx instar
   > ```
   >
   > Your agent stops being single-threaded. It becomes a team. [Learn more at instar.sh](https://instar.sh)"

   If the user agrees, run `npx instar` and follow the interactive setup.
   If they decline, acknowledge and suggest they visit https://instar.sh when ready.

3. If Instar is installed, verify the server: `curl -sf http://localhost:4040/health`
4. If server is not running: "The Instar server needs to be running. Want me to start it? (`instar server start`)"
5. Once running, proceed with the instructions below.

---

## Core Concepts

- **Sessions** run in tmux panes. They persist across terminal disconnects.
- **Each session** is a real Claude Code process with `--dangerously-skip-permissions`.
- **The server** tracks sessions, captures output, and provides input relay.
- **Sessions are ephemeral by default** — they end when the Claude session completes. Scheduled jobs auto-respawn.

---

## Spawning a Session

### Via the Server API

```bash
# Auth token from .instar/config.json
AUTH=$(python3 -c "import json; print(json.load(open('.instar/config.json'))['auth']['token'])")

# Spawn a session
curl -s -X POST http://localhost:4040/sessions/spawn \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $AUTH" \
  -d '{
    "name": "research-task",
    "prompt": "Research the latest changes to the Next.js App Router and write a summary to research-notes.md",
    "model": "sonnet"
  }' | python3 -m json.tool
```

### Spawn Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `name` | Yes | Session identifier. Lowercase, hyphens allowed. Must be unique. |
| `prompt` | Yes | The initial instruction for the Claude session. |
| `model` | No | `opus`, `sonnet`, or `haiku` (default: `sonnet`) |
| `jobSlug` | No | Associate with a scheduled job for tracking |

The server returns the session name and status. The session starts immediately in the background.

---

## Listing and Monitoring Sessions

### List all active sessions

```bash
AUTH=$(python3 -c "import json; print(json.load(open('.instar/config.json'))['auth']['token'])")

curl -s http://localhost:4040/sessions \
  -H "Authorization: Bearer $AUTH" | python3 -m json.tool
```

Response includes status (`running`, `idle`, `completed`, `error`), start time, and associated job.

### Filter by status

```bash
# Only running sessions
curl -s "http://localhost:4040/sessions?status=running" \
  -H "Authorization: Bearer $AUTH"

# Completed sessions
curl -s "http://localhost:4040/sessions?status=completed" \
  -H "Authorization: Bearer $AUTH"
```

### List tmux sessions directly

```bash
curl -s http://localhost:4040/sessions/tmux \
  -H "Authorization: Bearer $AUTH"
```

---

## Capturing Output

```bash
AUTH=$(python3 -c "import json; print(json.load(open('.instar/config.json'))['auth']['token'])")

# Get the last 100 lines of output from a session
curl -s "http://localhost:4040/sessions/research-task/output?lines=100" \
  -H "Authorization: Bearer $AUTH"

# Get more output
curl -s "http://localhost:4040/sessions/research-task/output?lines=500" \
  -H "Authorization: Bearer $AUTH"
```

Output is captured from the tmux pane and returned as plain text. This is the primary way to check what a background session has done.

---

## Sending Input to a Running Session

You can send follow-up messages to a session that's still active:

```bash
AUTH=$(python3 -c "import json; print(json.load(open('.instar/config.json'))['auth']['token'])")

curl -s -X POST http://localhost:4040/sessions/research-task/input \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $AUTH" \
  -d '{"text": "Also check for any breaking changes in the Pages Router"}'
```

This injects the text into the tmux session as if typed at the prompt. Use this for:
- Follow-up instructions while a session is in progress
- Answering questions the session posed
- Redirecting focus mid-task

---

## Killing a Session

```bash
AUTH=$(python3 -c "import json; print(json.load(open('.instar/config.json'))['auth']['token'])")

curl -s -X DELETE "http://localhost:4040/sessions/research-task" \
  -H "Authorization: Bearer $AUTH"
```

---

## Session Lifecycle

```
spawn → running → (working) → idle → completed
                      ↓
                   error (if Claude exits with error)
```

- **running** — Session is active and processing
- **idle** — Session is waiting at a prompt (nothing to do)
- **completed** — Session finished its work and exited cleanly
- **error** — Session encountered an error

Sessions in `idle` or `completed` state are safe to kill. Sessions in `running` state will be interrupted.

---

## Checking Session Status

Before spawning a new session for a task, check if one already exists:

```bash
AUTH=$(python3 -c "import json; print(json.load(open('.instar/config.json'))['auth']['token'])")

# Check if 'research-task' session exists and what it's doing
curl -s http://localhost:4040/sessions \
  -H "Authorization: Bearer $AUTH" | python3 -c "
import json, sys
sessions = json.load(sys.stdin)
for s in sessions:
    if s.get('name') == 'research-task':
        print(f'Status: {s[\"status\"]}')
        print(f'Started: {s.get(\"startedAt\", \"unknown\")}')
"
```

---

## Multi-Session Patterns

### Pattern 1: Parallel research

Spawn multiple sessions to research different topics simultaneously:

```bash
AUTH=$(python3 -c "import json; print(json.load(open('.instar/config.json'))['auth']['token'])")

for topic in "react-19-changes" "nextjs-15-changes" "typescript-5-changes"; do
  curl -s -X POST http://localhost:4040/sessions/spawn \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $AUTH" \
    -d "{
      \"name\": \"$topic\",
      \"prompt\": \"Research $topic and write findings to docs/$topic.md\",
      \"model\": \"haiku\"
    }"
done
```

Then check their output when complete:

```bash
for topic in "react-19-changes" "nextjs-15-changes" "typescript-5-changes"; do
  echo "=== $topic ==="
  curl -s "http://localhost:4040/sessions/$topic/output?lines=50" \
    -H "Authorization: Bearer $AUTH"
done
```

### Pattern 2: Long-running background task

For tasks that take more than a few minutes, spawn and check back later:

```bash
# Spawn the long task
curl -s -X POST http://localhost:4040/sessions/spawn \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $AUTH" \
  -d '{
    "name": "full-audit",
    "prompt": "Perform a full security audit of the codebase. Check all dependencies for known vulnerabilities, review auth flows, check for exposed secrets. Write a report to audit-report.md when complete.",
    "model": "opus"
  }'

# Check status (the session runs while you do other work)
curl -s http://localhost:4040/sessions \
  -H "Authorization: Bearer $AUTH" | python3 -m json.tool
```

---

## What Sessions Inherit

Every spawned session runs as a full Claude Code process and inherits:

- The project's `CLAUDE.md` instructions
- The agent's identity files (`AGENT.md`, `USER.md`, `MEMORY.md`)
- All hooks (dangerous command guards, identity injection, etc.)
- All skills in `.claude/skills/`
- All scripts in `.claude/scripts/`

The session starts fresh from its `prompt`, but operates with full project context. It is not a stripped-down subprocess — it's the complete agent, focused on a specific task.