Start, watch and read sessions from shell scripts, or over the local HTTP API.
Everything you can do in the UI is a command too, so you can drive sessions from scripts, make
targets or other tools. Commands print JSON where a script needs it.
# Start the test suite as the session's program, without attaching.rakumux new --detach --name tests -- cargo test --workspace# Wait up to ten minutes for it to finish.rakumux session wait tests --until exited --timeout 600000# Print the last 50 lines it wrote.rakumux session read tests --source recent --lines 50 | jq -r .text
Because the session holds the job, you can watch it live in Rakumux at the same time, and it keeps
running if your script’s terminal goes away.
rakumux session wait <name|id> --until U blocks until the session reaches a state, or until
--timeout milliseconds pass (default 30000). It prints {"matched", "status", "lifecycle", "reported", "reason"}.
--until
Waits until
settled
The agent stops working (idle, done or waiting for you), or the program ends
rakumux session read <name|id> prints {"text", "rows", "cols", "cursor", "truncated"}.
--source visible (the default) is the screen; recent and recent-unwrapped are the last
--lines lines of history. --format ansi keeps colours.
rakumux ls --all --json # every folder's sessionsrakumux session list # this folder's: {"sessions": [...]}rakumux session get tests # one: {"session": {...}}
Each session carries its status, lifecycle, agent, git context, the agent’s latest output and
your last prompt (agent_output, user_prompt), and its terminal size.
For other languages, or anything that can’t run a command, the
local HTTP API serves the same operations on 127.0.0.1, plus
WebSockets for session events and live terminals. It starts on demand:
jq is used only by these examples; Rakumux doesn’t need it.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Rakumux","description":"Terminal sessions for coding agents, in one fast terminal UI.","colors":{"primary":"#d9692a","light":"#ff9e64","dark":"#c85a1c"},"logo":{"light":"https://mintcdn.com/human-unsupervised-pty-ltd/mZ98KnFkRMJsaXOd/logo/light.svg?fit=max\u0026auto=format\u0026n=mZ98KnFkRMJsaXOd\u0026q=85\u0026s=16a9ca71ea1e16b851ab93e3d34b5ea7","dark":"https://mintcdn.com/human-unsupervised-pty-ltd/mZ98KnFkRMJsaXOd/logo/dark.svg?fit=max\u0026auto=format\u0026n=mZ98KnFkRMJsaXOd\u0026q=85\u0026s=b9eef03a9ddf9ac932d19bff61c5d469","href":"https://rakumux.com"},"favicon":"https://mintcdn.com/human-unsupervised-pty-ltd/mZ98KnFkRMJsaXOd/favicon.svg?fit=max\u0026auto=format\u0026n=mZ98KnFkRMJsaXOd\u0026q=85\u0026s=6aa6bca8a6274d330984efae6158d64c","api":{"playground":{"display":"simple"}},"appearance":{"default":"dark"},"background":{"color":{"light":"#ffffff","dark":"#101119"}},"navbar":{"links":[{"href":"https://rakumux.com","label":"rakumux.com"},{"href":"https://github.com/humanunsupervised/rakumux/releases","label":"Releases"}],"primary":{"type":"github","href":"https://github.com/humanunsupervised/rakumux"}},"footer":{"socials":{"github":"https://github.com/humanunsupervised/rakumux","website":"https://rakumux.com"}},"fonts":{"family":"Geist"},"contextual":{"options":["copy","view","chatgpt","claude"],"display":"header"},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"human-unsupervised-pty-ltd","hasAudioNarration":false,"actualSubdomain":"human-unsupervised-pty-ltd","customDomains":["rakumux.com"],"gitSource":{"type":"github","owner":"humanunsupervised","repo":"rakumux-cloud","deployBranch":"main","contentDirectory":"docs","isPrivate":true,"mountPath":"","label":"","_id":"6ade9d72ae0dc487a6155e47"},"chroma":{"latestBuiltDeploymentHistoryId":"6ae26b05b8121111e5b87ec8","collectionId":"4e0469bb-aed2-43b2-b770-b15bba515194","liveDeploymentHistoryId":"6ae26b05b8121111e5b87ec8","schemaVersion":"v3"},"entitlements":{"AI_CHAT":{"status":"ENABLED"},"WEB_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6ae33189217e82a3b924924c","clientVersion":"0.0.4006","searchFilterCounts":[{"language":"default","tag":"Guides","count":31},{"language":"default","tag":"API reference","count":14},{"language":"default","tag":"Endpoints","count":13},{"language":"default","tag":"Using Rakumux","count":8},{"language":"default","tag":"sessions","count":8},{"language":"default","tag":"Get started","count":5},{"language":"default","tag":"Coding agents","count":4},{"language":"default","tag":"Where to run it","count":4},{"language":"default","tag":"Account and AI titles","count":3},{"language":"default","tag":"Reference","count":3}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"/docs","hasChatPermissions":true,"hasWebMcpPermissions":true,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"pause-universal-search-reconcile","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"per-site-search-delta","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-private-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"byok-sep-25","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"vite-origin","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-updated-9-15","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":true},"customCss":[],"page":{"pagePath":"workflows/scripting","slug":"/workflows/scripting","pageMetadata":{"title":"Script Rakumux","description":"Start, watch and read sessions from shell scripts, or over the local HTTP API.","href":"/workflows/scripting"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Start, watch and read sessions from shell scripts, or over the local HTTP API.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,p:`p`,pre:`pre`,span:`span`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,..._provideComponents(),...props.components},{CodeBlock,Heading,Note,Table}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Note)_missingMdxReference(`Note`,true);if(!Table)_missingMdxReference(`Table`,true);return _jsxs(_Fragment,{children:[_jsxs(_components.p,{children:[`Everything you can do in the UI is a command too, so you can drive sessions from scripts, `,_jsx(_components.code,{children:`make`}),`\ntargets or other tools. Commands print JSON where a script needs it.`]}),`\n`,_jsx(Heading,{level:`2`,id:`run-a-job-in-a-session-and-wait-for-it`,children:`Run a job in a session and wait for it`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`8`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`8`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# Start the test suite as the session's program, without attaching.`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`rakumux`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` new`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --detach`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --name`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` tests`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` cargo`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` test`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --workspace`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# Wait up to ten minutes for it to finish.`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`rakumux`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` session`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` wait`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` tests`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --until`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` exited`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --timeout`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:` 600000`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# Print the last 50 lines it wrote.`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`rakumux`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` session`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` read`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` tests`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --source`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` recent`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --lines`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:` 50`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` |`}),_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:` jq`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -r`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` .text`})]}),`\n`]})})}),`\n`,_jsx(_components.p,{children:`Because the session holds the job, you can watch it live in Rakumux at the same time, and it keeps\nrunning if your script’s terminal goes away.`}),`\n`,_jsx(Heading,{level:`2`,id:`wait-for-something-to-happen`,children:`Wait for something to happen`}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`rakumux session wait \u003cname|id> --until U`}),` blocks until the session reaches a state, or until\n`,_jsx(_components.code,{children:`--timeout`}),` milliseconds pass (default 30000). It prints `,_jsx(_components.code,{children:`{\"matched\", \"status\", \"lifecycle\", \"reported\", \"reason\"}`}),`.`]}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:_jsx(_components.code,{children:`--until`})}),_jsx(_components.th,{children:`Waits until`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`settled`})}),_jsx(_components.td,{children:`The agent stops working (idle, done or waiting for you), or the program ends`})]}),_jsxs(_components.tr,{children:[_jsxs(_components.td,{children:[_jsx(_components.code,{children:`idle`}),`, `,_jsx(_components.code,{children:`working`}),`, `,_jsx(_components.code,{children:`blocked`})]}),_jsx(_components.td,{children:`The agent is in that state`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`exited`})}),_jsx(_components.td,{children:`The program ends`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`reported`})}),_jsx(_components.td,{children:`The session reports something`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`output`})}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`--pattern`}),` appears in its output`]})]})]})]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`rakumux`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` session`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` wait`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` dev-server`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --until`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` output`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --pattern`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"ready on\"`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --timeout`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:` 60000`})]}),`\n`]})})}),`\n`,_jsx(Heading,{level:`2`,id:`read-a-session`,children:`Read a session`}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`rakumux session read \u003cname|id>`}),` prints `,_jsx(_components.code,{children:`{\"text\", \"rows\", \"cols\", \"cursor\", \"truncated\"}`}),`.\n`,_jsx(_components.code,{children:`--source visible`}),` (the default) is the screen; `,_jsx(_components.code,{children:`recent`}),` and `,_jsx(_components.code,{children:`recent-unwrapped`}),` are the last\n`,_jsx(_components.code,{children:`--lines`}),` lines of history. `,_jsx(_components.code,{children:`--format ansi`}),` keeps colours.`]}),`\n`,_jsx(Heading,{level:`2`,id:`list-sessions`,children:`List sessions`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`3`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`3`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`rakumux`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` ls`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --all`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --json`}),_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:` # every folder's sessions`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`rakumux`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` session`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` list`}),_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:` # this folder's: {\"sessions\": [...]}`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`rakumux`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` session`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` get`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` tests`}),_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:` # one: {\"session\": {...}}`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Each session carries its `,_jsx(_components.code,{children:`status`}),`, `,_jsx(_components.code,{children:`lifecycle`}),`, `,_jsx(_components.code,{children:`agent`}),`, git context, the agent’s latest output and\nyour last prompt (`,_jsx(_components.code,{children:`agent_output`}),`, `,_jsx(_components.code,{children:`user_prompt`}),`), and its terminal size.`]}),`\n`,_jsx(Heading,{level:`2`,id:`over-http`,children:`Over HTTP`}),`\n`,_jsxs(_components.p,{children:[`For other languages, or anything that can’t run a command, the\n`,_jsx(_components.a,{href:`/api-reference/introduction`,children:`local HTTP API`}),` serves the same operations on `,_jsx(_components.code,{children:`127.0.0.1`}),`, plus\nWebSockets for session events and live terminals. It starts on demand:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`3`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`3`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`rakumux-api`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --detach`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`API`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`$(`}),_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`jq`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -r`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` .url`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` ~/.rakumux/api.json`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`); `}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`TOKEN`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`$(`}),_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`jq`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -r`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` .token`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` ~/.rakumux/api.json`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`curl`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -s`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Authorization: Bearer `}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`$TOKEN`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`$API`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`/v1/sessions?all=true\"`})]}),`\n`]})})}),`\n`,_jsx(Note,{children:_jsxs(_components.p,{children:[_jsx(_components.code,{children:`jq`}),` is used only by these examples; Rakumux doesn’t need it.`]})})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Script Rakumux","description":"Start, watch and read sessions from shell scripts, or over the local HTTP API.","href":"/workflows/scripting"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Run a job in a session and wait for it","slug":"run-a-job-in-a-session-and-wait-for-it","depth":2,"children":[]},{"title":"Wait for something to happen","slug":"wait-for-something-to-happen","depth":2,"children":[]},{"title":"Read a session","slug":"read-a-session","depth":2,"children":[]},{"title":"List sessions","slug":"list-sessions","depth":2,"children":[]},{"title":"Over HTTP","slug":"over-http","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"human-unsupervised-pty-ltd","siteName":"Rakumux","title":"Script Rakumux - Rakumux","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-26T00:24:07.793Z","originalFileLocation":"workflows/scripting.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"dark\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Start, watch and read sessions from shell scripts, or over the local HTTP API.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Rakumux\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/docs/mintlify-assets/_mintlify/favicons/human-unsupervised-pty-ltd/T2YdgaTW8imvJoWH/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/docs/mintlify-assets/_mintlify/favicons/human-unsupervised-pty-ltd/T2YdgaTW8imvJoWH/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/docs/mintlify-assets/_mintlify/favicons/human-unsupervised-pty-ltd/T2YdgaTW8imvJoWH/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/docs/mintlify-assets/_mintlify/favicons/human-unsupervised-pty-ltd/T2YdgaTW8imvJoWH/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/docs/mintlify-assets/_mintlify/favicons/human-unsupervised-pty-ltd/T2YdgaTW8imvJoWH/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/docs/mintlify-assets/_mintlify/favicons/human-unsupervised-pty-ltd/T2YdgaTW8imvJoWH/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/docs/mintlify-assets/_mintlify/favicons/human-unsupervised-pty-ltd/T2YdgaTW8imvJoWH/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/docs/mintlify-assets/_mintlify/favicons/human-unsupervised-pty-ltd/T2YdgaTW8imvJoWH/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/docs/mintlify-assets/_mintlify/favicons/human-unsupervised-pty-ltd/T2YdgaTW8imvJoWH/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Script Rakumux - Rakumux\">\u003cmeta data-mint-head property=\"og:description\" content=\"Start, watch and read sessions from shell scripts, or over the local HTTP API.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Rakumux\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://rakumux.com/docs/workflows/scripting\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://human-unsupervised-pty-ltd.mintlify.app/_mintlify/api/og/v2?division=Workflows\u0026amp;title=Script+Rakumux\u0026amp;description=Start%2C+watch+and+read+sessions+from+shell+scripts%2C+or+over+the+local+HTTP+API.\u0026amp;theme=e19a71dbfbaba376e1df0768\u0026amp;signature=ffbe3565673be0d92db5354a0126fc236c87bdc218220606d8bd220595ce7209\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Script Rakumux - Rakumux\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Start, watch and read sessions from shell scripts, or over the local HTTP API.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://human-unsupervised-pty-ltd.mintlify.app/_mintlify/api/og/v2?division=Workflows\u0026amp;title=Script+Rakumux\u0026amp;description=Start%2C+watch+and+read+sessions+from+shell+scripts%2C+or+over+the+local+HTTP+API.\u0026amp;theme=e19a71dbfbaba376e1df0768\u0026amp;signature=ffbe3565673be0d92db5354a0126fc236c87bdc218220606d8bd220595ce7209\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/docs/mintlify-assets/_mintlify/favicons/human-unsupervised-pty-ltd/T2YdgaTW8imvJoWH/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Rakumux\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#d9692a\">\u003clink data-mint-head rel=\"canonical\" href=\"https://rakumux.com/docs/workflows/scripting\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/docs/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/docs/workflows/scripting.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://rakumux.com/#organization\",\"name\":\"Rakumux\",\"url\":\"https://rakumux.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/human-unsupervised-pty-ltd/mZ98KnFkRMJsaXOd/logo/light.svg?fit=max\u0026auto=format\u0026n=mZ98KnFkRMJsaXOd\u0026q=85\u0026s=16a9ca71ea1e16b851ab93e3d34b5ea7\"}},{\"@type\":\"WebSite\",\"@id\":\"https://rakumux.com/docs#website\",\"name\":\"Rakumux\",\"url\":\"https://rakumux.com/docs\",\"publisher\":{\"@id\":\"https://rakumux.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://rakumux.com/docs/workflows/scripting#webpage\",\"url\":\"https://rakumux.com/docs/workflows/scripting\",\"name\":\"Script Rakumux\",\"description\":\"Start, watch and read sessions from shell scripts, or over the local HTTP API.\",\"dateModified\":\"2026-10-26T00:24:07.793Z\",\"isPartOf\":{\"@id\":\"https://rakumux.com/docs#website\"},\"breadcrumb\":{\"@id\":\"https://rakumux.com/docs/workflows/scripting#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://rakumux.com/docs/workflows/scripting#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Workflows\",\"item\":\"https://rakumux.com/docs/workflows/parallel-agents\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Script Rakumux\",\"item\":\"https://rakumux.com/docs/workflows/scripting\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://rakumux.com/docs/workflows/scripting#article\",\"headline\":\"Script Rakumux\",\"name\":\"Script Rakumux\",\"description\":\"Start, watch and read sessions from shell scripts, or over the local HTTP API.\",\"url\":\"https://rakumux.com/docs/workflows/scripting\",\"mainEntityOfPage\":{\"@id\":\"https://rakumux.com/docs/workflows/scripting#webpage\"},\"dateModified\":\"2026-10-26T00:24:07.793Z\",\"publisher\":{\"@id\":\"https://rakumux.com/#organization\"},\"isPartOf\":{\"@id\":\"https://rakumux.com/docs#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Rakumux\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"Rakumux","nav":{"global":null,"tabs":[{"tab":"Guides","icon":"book-open","groups":[{"group":"Get started","pages":[{"title":"Rakumux","sidebarTitle":"Introduction","href":""},{"title":"Quickstart","href":"/quickstart"},{"title":"Installation","href":"/installation"},{"title":"How Rakumux works","href":"/concepts"},{"title":"Architecture","href":"/architecture"}]},{"group":"Where to run it","pages":[{"title":"Where to run Rakumux","href":"/remote/index"},{"title":"Your own server","href":"/remote/own-server"},{"title":"A Fly Machine","href":"/remote/fly-machines"},{"title":"A Fly Sprite","href":"/remote/fly-sprites"}]},{"group":"Workflows","pages":[{"title":"Run agents in parallel","href":"/workflows/parallel-agents"},{"title":"Agents that use Rakumux","description":"Let an agent start helper sessions, read other sessions' output and report its own status.","href":"/workflows/agents-using-rakumux"},{"title":"Script Rakumux","href":"/workflows/scripting"}]},{"group":"Using Rakumux","pages":[{"title":"Sessions","description":"Create, rename, pin, close, restart and revive sessions.","href":"/guides/sessions"},{"title":"The session list","href":"/guides/session-list"},{"title":"Agents' messages","href":"/guides/session-descriptions"},{"title":"Layouts","href":"/guides/layouts"},{"title":"Terminal panel","href":"/guides/terminal-panel"},{"title":"Settings","href":"/guides/settings"},{"title":"Keyboard and mouse","href":"/guides/keyboard-and-mouse"},{"title":"Restarts and recovery","href":"/guides/recovery"}]},{"group":"Coding agents","pages":[{"title":"Coding agents","sidebarTitle":"Overview","href":"/agents/overview"},{"title":"Activity hooks","href":"/agents/activity-hooks"},{"title":"MCP server","href":"/agents/mcp"},{"title":"AI naming","href":"/agents/ai-naming"}]},{"group":"Account and AI titles","pages":[{"title":"Sign in","href":"/account/sign-in"},{"title":"AI session titles","href":"/account/ai-titles"},{"title":"Agent feed","href":"/account/feed"}]},{"group":"Phone access","pages":[{"title":"Phone access","sidebarTitle":"Set up phone access","href":"/phone/remote-access"}]},{"group":"Reference","pages":[{"title":"CLI reference","href":"/reference/cli"},{"title":"Configuration","href":"/reference/configuration"},{"title":"Troubleshooting","href":"/reference/troubleshooting"}]}]},{"tab":"API reference","icon":"square-terminal","pages":[{"title":"API reference","href":"/api-reference/introduction"}]}]},"title":"Script Rakumux - Rakumux","buildId":"dpl_AUojGTPodKNPTVaxVPcxnNvkSVqo","deploymentId":"dpl_AUojGTPodKNPTVaxVPcxnNvkSVqo","dynamics":[],"chunks":[]}
