{"id":"53d54395-0ee0-4465-9d5e-882fbf9de457","shortId":"dCUXAR","kind":"skill","title":"instar-session","tagline":"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. Trigg","description":"# instar-session — Persistent Agent Session Management\n\nInstar 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.\n\n## Getting Started\n\nBefore using this skill, check if Instar is available:\n\n1. Check for Instar: `ls .instar/config.json 2>/dev/null || which instar 2>/dev/null`\n2. If neither exists, Instar is not installed. Tell the user:\n\n   > \"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.\n   >\n   > **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.\n   >\n   > It takes about 2 minutes to set up. One command:\n   >\n   > ```\n   > npx instar\n   > ```\n   >\n   > Your agent stops being single-threaded. It becomes a team. [Learn more at instar.sh](https://instar.sh)\"\n\n   If the user agrees, run `npx instar` and follow the interactive setup.\n   If they decline, acknowledge and suggest they visit https://instar.sh when ready.\n\n3. If Instar is installed, verify the server: `curl -sf http://localhost:4040/health`\n4. If server is not running: \"The Instar server needs to be running. Want me to start it? (`instar server start`)\"\n5. Once running, proceed with the instructions below.\n\n---\n\n## Core Concepts\n\n- **Sessions** run in tmux panes. They persist across terminal disconnects.\n- **Each session** is a real Claude Code process with `--dangerously-skip-permissions`.\n- **The server** tracks sessions, captures output, and provides input relay.\n- **Sessions are ephemeral by default** — they end when the Claude session completes. Scheduled jobs auto-respawn.\n\n---\n\n## Spawning a Session\n\n### Via the Server API\n\n```bash\n# Auth token from .instar/config.json\nAUTH=$(python3 -c \"import json; print(json.load(open('.instar/config.json'))['auth']['token'])\")\n\n# Spawn a session\ncurl -s -X POST http://localhost:4040/sessions/spawn \\\n  -H 'Content-Type: application/json' \\\n  -H \"Authorization: Bearer $AUTH\" \\\n  -d '{\n    \"name\": \"research-task\",\n    \"prompt\": \"Research the latest changes to the Next.js App Router and write a summary to research-notes.md\",\n    \"model\": \"sonnet\"\n  }' | python3 -m json.tool\n```\n\n### Spawn Parameters\n\n| Parameter | Required | Description |\n|-----------|----------|-------------|\n| `name` | Yes | Session identifier. Lowercase, hyphens allowed. Must be unique. |\n| `prompt` | Yes | The initial instruction for the Claude session. |\n| `model` | No | `opus`, `sonnet`, or `haiku` (default: `sonnet`) |\n| `jobSlug` | No | Associate with a scheduled job for tracking |\n\nThe server returns the session name and status. The session starts immediately in the background.\n\n---\n\n## Listing and Monitoring Sessions\n\n### List all active sessions\n\n```bash\nAUTH=$(python3 -c \"import json; print(json.load(open('.instar/config.json'))['auth']['token'])\")\n\ncurl -s http://localhost:4040/sessions \\\n  -H \"Authorization: Bearer $AUTH\" | python3 -m json.tool\n```\n\nResponse includes status (`running`, `idle`, `completed`, `error`), start time, and associated job.\n\n### Filter by status\n\n```bash\n# Only running sessions\ncurl -s \"http://localhost:4040/sessions?status=running\" \\\n  -H \"Authorization: Bearer $AUTH\"\n\n# Completed sessions\ncurl -s \"http://localhost:4040/sessions?status=completed\" \\\n  -H \"Authorization: Bearer $AUTH\"\n```\n\n### List tmux sessions directly\n\n```bash\ncurl -s http://localhost:4040/sessions/tmux \\\n  -H \"Authorization: Bearer $AUTH\"\n```\n\n---\n\n## Capturing Output\n\n```bash\nAUTH=$(python3 -c \"import json; print(json.load(open('.instar/config.json'))['auth']['token'])\")\n\n# Get the last 100 lines of output from a session\ncurl -s \"http://localhost:4040/sessions/research-task/output?lines=100\" \\\n  -H \"Authorization: Bearer $AUTH\"\n\n# Get more output\ncurl -s \"http://localhost:4040/sessions/research-task/output?lines=500\" \\\n  -H \"Authorization: Bearer $AUTH\"\n```\n\nOutput is captured from the tmux pane and returned as plain text. This is the primary way to check what a background session has done.\n\n---\n\n## Sending Input to a Running Session\n\nYou can send follow-up messages to a session that's still active:\n\n```bash\nAUTH=$(python3 -c \"import json; print(json.load(open('.instar/config.json'))['auth']['token'])\")\n\ncurl -s -X POST http://localhost:4040/sessions/research-task/input \\\n  -H 'Content-Type: application/json' \\\n  -H \"Authorization: Bearer $AUTH\" \\\n  -d '{\"text\": \"Also check for any breaking changes in the Pages Router\"}'\n```\n\nThis injects the text into the tmux session as if typed at the prompt. Use this for:\n- Follow-up instructions while a session is in progress\n- Answering questions the session posed\n- Redirecting focus mid-task\n\n---\n\n## Killing a Session\n\n```bash\nAUTH=$(python3 -c \"import json; print(json.load(open('.instar/config.json'))['auth']['token'])\")\n\ncurl -s -X DELETE \"http://localhost:4040/sessions/research-task\" \\\n  -H \"Authorization: Bearer $AUTH\"\n```\n\n---\n\n## Session Lifecycle\n\n```\nspawn → running → (working) → idle → completed\n                      ↓\n                   error (if Claude exits with error)\n```\n\n- **running** — Session is active and processing\n- **idle** — Session is waiting at a prompt (nothing to do)\n- **completed** — Session finished its work and exited cleanly\n- **error** — Session encountered an error\n\nSessions in `idle` or `completed` state are safe to kill. Sessions in `running` state will be interrupted.\n\n---\n\n## Checking Session Status\n\nBefore spawning a new session for a task, check if one already exists:\n\n```bash\nAUTH=$(python3 -c \"import json; print(json.load(open('.instar/config.json'))['auth']['token'])\")\n\n# Check if 'research-task' session exists and what it's doing\ncurl -s http://localhost:4040/sessions \\\n  -H \"Authorization: Bearer $AUTH\" | python3 -c \"\nimport json, sys\nsessions = json.load(sys.stdin)\nfor s in sessions:\n    if s.get('name') == 'research-task':\n        print(f'Status: {s[\\\"status\\\"]}')\n        print(f'Started: {s.get(\\\"startedAt\\\", \\\"unknown\\\")}')\n\"\n```\n\n---\n\n## Multi-Session Patterns\n\n### Pattern 1: Parallel research\n\nSpawn multiple sessions to research different topics simultaneously:\n\n```bash\nAUTH=$(python3 -c \"import json; print(json.load(open('.instar/config.json'))['auth']['token'])\")\n\nfor topic in \"react-19-changes\" \"nextjs-15-changes\" \"typescript-5-changes\"; do\n  curl -s -X POST http://localhost:4040/sessions/spawn \\\n    -H 'Content-Type: application/json' \\\n    -H \"Authorization: Bearer $AUTH\" \\\n    -d \"{\n      \\\"name\\\": \\\"$topic\\\",\n      \\\"prompt\\\": \\\"Research $topic and write findings to docs/$topic.md\\\",\n      \\\"model\\\": \\\"haiku\\\"\n    }\"\ndone\n```\n\nThen check their output when complete:\n\n```bash\nfor topic in \"react-19-changes\" \"nextjs-15-changes\" \"typescript-5-changes\"; do\n  echo \"=== $topic ===\"\n  curl -s \"http://localhost:4040/sessions/$topic/output?lines=50\" \\\n    -H \"Authorization: Bearer $AUTH\"\ndone\n```\n\n### Pattern 2: Long-running background task\n\nFor tasks that take more than a few minutes, spawn and check back later:\n\n```bash\n# Spawn the long task\ncurl -s -X POST http://localhost:4040/sessions/spawn \\\n  -H 'Content-Type: application/json' \\\n  -H \"Authorization: Bearer $AUTH\" \\\n  -d '{\n    \"name\": \"full-audit\",\n    \"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.\",\n    \"model\": \"opus\"\n  }'\n\n# Check status (the session runs while you do other work)\ncurl -s http://localhost:4040/sessions \\\n  -H \"Authorization: Bearer $AUTH\" | python3 -m json.tool\n```\n\n---\n\n## What Sessions Inherit\n\nEvery spawned session runs as a full Claude Code process and inherits:\n\n- The project's `CLAUDE.md` instructions\n- The agent's identity files (`AGENT.md`, `USER.md`, `MEMORY.md`)\n- All hooks (dangerous command guards, identity injection, etc.)\n- All skills in `.claude/skills/`\n- All scripts in `.claude/scripts/`\n\nThe 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.","tags":["instar","session","jkheadley","agent-framework","agent-identity","agent-infrastructure","agent-memory","agent-skills","ai-agents","ai-safety","autonomous-agents","claude-code"],"capabilities":["skill","source-jkheadley","skill-instar-session","topic-agent-framework","topic-agent-identity","topic-agent-infrastructure","topic-agent-memory","topic-agent-skills","topic-ai-agents","topic-ai-safety","topic-autonomous-agents","topic-claude-code","topic-cli","topic-cron","topic-job-scheduler"],"categories":["instar"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/JKHeadley/instar/instar-session","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add JKHeadley/instar","source_repo":"https://github.com/JKHeadley/instar","install_from":"skills.sh"}},"qualityScore":"0.479","qualityRationale":"deterministic score 0.48 from registry signals: · indexed on github topic:agent-skills · 59 github stars · SKILL.md body (8,586 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-02T06:55:53.505Z","embedding":null,"createdAt":"2026-04-18T22:14:36.868Z","updatedAt":"2026-05-02T06:55:53.505Z","lastSeenAt":"2026-05-02T06:55:53.505Z","tsv":"'-15':951,1001 '-19':948,998 '-5':954,1004 '/dev/null':118,122 '1':111,921 '100':604,616 '2':117,121,123,238,1022 '20':215 '3':286 '4':298 '4040/health':297 '4040/sessions':525,555,567,882,1012,1111 '4040/sessions/research-task':775 '4040/sessions/research-task/input':696 '4040/sessions/research-task/output':614,627 '4040/sessions/spawn':410,962,1052 '4040/sessions/tmux':582 '5':319 '50':1015 '500':629 'abil':179 'access':90,198 'acknowledg':278 'across':336 'activ':508,678,796 'agent':56,137,177,248,1140,1188 'agent.md':1144 'agre':266 'allow':457 'alreadi':853 'also':708 'answer':745 'api':385 'app':433 'application/json':415,701,967,1057 'ask':32,146,154 'associ':480,543 'audit':160,212,1066,1072 'audit-report.md':1093 'auth':387,391,400,419,511,520,529,561,573,586,590,599,620,633,680,689,705,759,768,779,856,865,886,933,942,971,1019,1061,1083,1115 'author':417,527,559,571,584,618,631,703,777,884,969,1017,1059,1113 'auto':377 'auto-respawn':376 'avail':110 'back':229,1040 'background':16,38,72,221,501,655,1026 'bash':386,510,548,578,589,679,758,855,932,993,1042 'bearer':418,528,560,572,585,619,632,704,778,885,970,1018,1060,1114 'becom':255 'block':25 'break':712 'c':393,513,592,682,761,858,888,935 'captur':356,587,636 'chang':429,713,949,952,955,999,1002,1005 'check':106,112,201,652,709,839,850,867,988,1039,1076,1085,1098 'claud':10,67,81,344,371,468,789,1129 'claude.md':1137 'claude/scripts':1162 'claude/skills':1158 'clean':816 'close':167,225 'code':11,68,82,345,1130 'codebas':1075 'come':228 'command':244,1150 'communic':7,65 'complet':373,538,562,569,786,809,826,992,1095,1187 'concept':328 'content':413,699,965,1055 'content-typ':412,698,964,1054 'context':49,87,1175 'core':327 'curl':294,405,522,552,564,579,611,624,691,770,879,957,1009,1047,1108 'current':27 'd':420,706,972,1062 'danger':349,1149 'dangerously-skip-permiss':348 'declin':277 'deep':210 'default':366,476 'delet':773 'depend':1078 'descript':450 'die':173 'differ':929 'direct':577 'disconnect':338 'doc':982 'done':207,658,986,1020 'echo':1007 'encount':819 'end':368 'ephemer':364 'error':539,787,792,817,821 'etc':1154 'everi':1122 'exist':126,854,873 'exit':790,815 'expos':1087 'f':906,911 'file':1143 'filter':545 'find':980 'finish':811 'flow':1084 'focus':751,1189 'follow':271,669,736 'follow-up':668,735 'fresh':1166 'full':80,196,1065,1070,1128,1173 'full-audit':1064 'get':100,601,621 'give':175 'guard':1151 'h':411,416,526,558,570,583,617,630,697,702,776,883,963,968,1016,1053,1058,1112 'haiku':475,985 'hook':1148 'hyphen':456 'ident':1142,1152 'identifi':454 'idl':537,785,799,824 'immedi':498 'import':394,514,593,683,762,859,889,936 'includ':534 'independ':93 'inherit':1121,1133 'initi':464 'inject':719,1153 'input':360,660 'instal':130,290 'instanc':83 'instar':2,53,59,108,114,120,127,174,246,269,288,305,316 'instar-sess':1,52 'instar.sh':261,262,283 'instar/config.json':116,390,399,519,598,688,767,864,941 'instruct':325,465,738,1138 'interact':273 'interrupt':838 'job':375,484,544 'jobslug':478 'json':395,515,594,684,763,860,890,937 'json.load':397,517,596,686,765,862,893,939 'json.tool':445,532,1118 'keep':223 'kept':233 'kill':755,831 'known':1080 'laptop':227 'last':603 'later':1041 'latest':428 'learn':258 'let':60 'lifecycl':92,781 'line':605,615,628,1014 'list':502,506,574 'localhost':296,409,524,554,566,581,613,626,695,774,881,961,1011,1051,1110 'lock':165 'long':43,159,1024,1045 'long-run':42,1023 'lowercas':455 'ls':115 'm':444,531,1117 'manag':58 'memory.md':1146 'messag':671 'mid':753 'mid-task':752 'minut':216,239,1036 'model':441,470,984,1096 'monitor':5,63,504 'multi':917 'multi-sess':916 'multipl':925 'must':458 'name':421,451,492,901,973,1063 'need':21,46,183,208,307 'neither':125 'new':845 'next.js':432 'nextj':950,1000 'noth':806 'npx':245,268 'one':141,243,852 'open':398,518,597,687,766,863,940 'oper':1171 'opus':472,1097 'output':357,588,607,623,634,990 'page':716 'pane':333,640 'parallel':193,922 'paramet':447,448 'pattern':919,920,1021 'perform':1068 'permiss':351 'persist':9,55,335 'plain':644 'pose':749 'post':408,694,960,1050 'primari':649 'print':396,516,595,685,764,861,905,910,938 'proceed':322 'process':73,346,798,1131 'progress':744 'project':1135,1174 'prompt':425,461,731,805,975,1067,1169 'provid':359 'python3':392,443,512,530,591,681,760,857,887,934,1116 'question':746 're':206 'react':947,997 'readi':285 'real':343 'redirect':750 'relay':361 'report':1091 'requir':449 'research':149,186,423,426,870,903,923,928,976 'research-notes.md':440 'research-task':422,869,902 'respawn':378 'respons':533 'result':203 'return':489,642 'review':1082 'right':134 'router':434,717 'run':13,23,44,70,157,191,234,267,303,310,321,330,536,550,557,663,783,793,834,1025,1102,1125 's.get':900,913 'safe':829 'schedul':374,483 'script':1160 'secret':1088 'secur':211,1071 'send':659,667 'server':293,300,306,317,353,384,488 'session':3,12,28,54,57,69,77,96,189,232,329,340,355,362,372,381,404,453,469,491,496,505,509,551,563,576,610,656,664,674,725,741,748,757,780,794,800,810,818,822,832,840,846,872,892,898,918,926,1101,1120,1124,1164 'set':241 'setup':274 'sf':295 'simultan':931 'singl':252 'single-thread':251 'skill':105,1156 'skill-instar-session' 'skip':350 'someth':35,150 'sonnet':442,473,477 'source-jkheadley' 'spawn':4,62,98,181,187,217,379,402,446,782,843,924,1037,1043,1123 'specif':1192 'start':101,314,318,497,540,912,1165 'startedat':914 'state':827,835 'status':494,535,547,556,568,841,907,909,1099 'still':677 'stop':249 'strip':1181 'stripped-down':1180 'subprocess':1183 'suggest':280 'summari':438 'sys':891 'sys.stdin':894 'take':214,236,1031 'task':20,45,424,754,849,871,904,1027,1029,1046,1193 'team':257 'tell':131 'termin':163,337 'text':645,707,721 'thing':142,185 'thread':253 'three':184,188 'time':145,541 'tmux':75,332,575,639,724 'token':388,401,521,600,690,769,866,943 'tomorrow':230 'tool':89,197 'topic':930,945,974,977,995,1008 'topic-agent-framework' 'topic-agent-identity' 'topic-agent-infrastructure' 'topic-agent-memory' 'topic-agent-skills' 'topic-ai-agents' 'topic-ai-safety' 'topic-autonomous-agents' 'topic-claude-code' 'topic-cli' 'topic-cron' 'topic-job-scheduler' 'topic.md':983 'topic/output':1013 'track':354,486 'trigg':51 'type':414,700,728,966,1056 'typescript':953,1003 'uniqu':460 'unknown':915 'use':17,103,732 'user':31,133,265 'user.md':1145 'verifi':291 'via':382 'visit':282 'vulner':1081 'wait':153,802 'want':311 'way':650 'window':50,88,169 'without':24 'work':172,224,784,813,1107 'write':436,979,1089 'x':407,693,772,959,1049 'yes':452,462","prices":[{"id":"263769fc-042b-4152-8f95-c070305fb570","listingId":"53d54395-0ee0-4465-9d5e-882fbf9de457","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"JKHeadley","category":"instar","install_from":"skills.sh"},"createdAt":"2026-04-18T22:14:36.868Z"}],"sources":[{"listingId":"53d54395-0ee0-4465-9d5e-882fbf9de457","source":"github","sourceId":"JKHeadley/instar/instar-session","sourceUrl":"https://github.com/JKHeadley/instar/tree/main/skills/instar-session","isPrimary":false,"firstSeenAt":"2026-04-18T22:14:36.868Z","lastSeenAt":"2026-05-02T06:55:53.505Z"}],"details":{"listingId":"53d54395-0ee0-4465-9d5e-882fbf9de457","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"JKHeadley","slug":"instar-session","github":{"repo":"JKHeadley/instar","stars":59,"topics":["agent-framework","agent-identity","agent-infrastructure","agent-memory","agent-skills","ai-agents","ai-safety","autonomous-agents","claude-code","cli","cron","job-scheduler","llm","mcp","npm-package","open-source","persistency","telegram-bot","typescript","whatsapp"],"license":"mit","html_url":"https://github.com/JKHeadley/instar","pushed_at":"2026-05-02T05:23:59Z","description":"Persistent Claude Code agents with scheduling, sessions, memory, and Telegram.","skill_md_sha":"f6e16ca070193f2fee7611a25d4f06c0828bb90e","skill_md_path":"skills/instar-session/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/JKHeadley/instar/tree/main/skills/instar-session"},"layout":"multi","source":"github","category":"instar","frontmatter":{"name":"instar-session","license":"MIT","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.","compatibility":"Works best with instar (npx instar). If not installed, the skill will guide you through setup."},"skills_sh_url":"https://skills.sh/JKHeadley/instar/instar-session"},"updatedAt":"2026-05-02T06:55:53.505Z"}}