SDK & Headless - 100xprompt

Everything you do interactively with 100xprompt can also be automated. Run a single task from a script and collect the result as JSON, wire it into a CI check that comments on pull requests, or embed 100xprompt inside your own tooling with the official client. This page turns 100xprompt from an interactive assistant into a programmable engine your systems can call.

This page covers two ways to automate 100xprompt: the headless run command (best for shell scripts, cron jobs, and CI) and the official SDK client (best for embedding sessions inside your own application). Both drive the same engine - pick whichever fits how you want to invoke it.

Understand the shape

Whether you call it from a shell script or from code, the shape is the same. Your automation hands 100xprompt a prompt. 100xprompt does the work against your project. You get results back - as human-readable output, or as a stream of structured events you can parse.

The engine plans, edits files, runs commands, and calls tools exactly as it does in the interactive experience - the only difference is that a program is driving instead of a person, and the output is designed to be captured and parsed.

Pick an entry point

Two entry points drive the same engine. Reach for the headless run command from shells and CI; reach for the official client when you embed sessions in your own code.

I want to…	Best option
Script a one-off task from a shell, cron job, or CI	Headless `run` command
Pipe a diff or log into a task and parse the result	Headless `run` with `--format json`
Embed sessions inside my own application	Official client (`@100xprompt/sdk`)
Fan many tasks out in parallel	Official client, one session per unit of work

Headless CLI (run)
Official client (SDK)

The run command executes a single task and exits. It’s the fastest way to script 100xprompt - no code required, just a command with a message.

# Run a one-shot task in the current project
100xprompt run "Add input validation to the signup form and run the tests"

# Machine-readable output for scripts and CI
100xprompt run --format json "Summarize the changes on this branch"

# Pick a model, agent, or reasoning effort
100xprompt run --model 100xprompt/pro --agent review "Review the diff"

# Attach files to the prompt
100xprompt run -f src/app.ts -f src/util.ts "Write tests for every public function"

Prompts can also be piped in from another command, which makes run easy to compose in a shell:

git diff main | 100xprompt run --format json "Review this diff for correctness bugs"

Use --format json any time a machine reads the output. The default format is tuned for humans reading a terminal; the JSON format emits one structured event per line, ready to pipe into jq or your CI logic.

The official client, @100xprompt/sdk, lets you drive sessions programmatically from your own application. You create a session, send it a prompt, and receive results - with full control over how you orchestrate multiple tasks.

import { create100XPromptClient, create100XPromptServer } from "@100xprompt/sdk"

// Start a local engine and connect a client to it
const server = await create100XPromptServer()
const client = create100XPromptClient({ baseUrl: server.url })

// Create a session and send it a task
const session = await client.session.create()

await client.session.prompt({
  sessionID: session.data.id,
  parts: [
    { type: "text", text: "Write tests for every public function in this file." },
    { type: "file", mime: "text/plain", url: "file://src/app.ts" },
  ],
})

Because sessions are independent, you can fan work out across many of them in parallel - one per file, one per task, one per branch:

await Promise.all(
  files.map(async (file) => {
    const session = await client.session.create()
    await client.session.prompt({
      sessionID: session.data.id,
      parts: [
        { type: "text", text: "Add missing JSDoc to every export." },
        { type: "file", mime: "text/plain", url: `file://${file}` },
      ],
    })
  }),
)

The client can also connect to an already-running 100xprompt engine instead of starting its own - point baseUrl at the address it’s listening on and reuse it across many prompts.

Reference the `run` flags

The headless command mirrors the flexibility of the interactive experience. The most useful flags:

Flag	Alias	What it does
`--format`		Output style: `default` (formatted for humans) or `json` (structured events)
`--model`	`-m`	Model to use, as `provider/model`
`--agent`		Run the task with a specific agent
`--variant`		Reasoning effort for the model (for example `high`, `max`, `minimal`)
`--file`	`-f`	Attach one or more files to the prompt (repeatable)
`--continue`	`-c`	Continue the most recent session
`--session`	`-s`	Continue a specific session by id
`--title`		Set a title for the session
`--command`		Run a named command, passing the message as its arguments
`--share`		Share the session and print a link to it

You can also pipe the prompt in on standard input - anything on stdin is appended to the message. This makes it natural to feed a diff, a log, or a file’s contents straight into a task.

Parse the JSON event stream

Suppose a script needs to know what the agent did, not just read a paragraph. With --format json, 100xprompt emits one JSON object per line as the task progresses - a stream you consume incrementally or collect and inspect at the end. Each event carries a type, a timestamp, and the sessionID it belongs to. The stream lets you watch the whole task unfold: when a step begins and finishes, each tool the agent runs, the text it produces, and any error it hits.

{"type":"step_start","timestamp":1719830400000,"sessionID":"ses_abc123"}
{"type":"tool_use","timestamp":1719830401200,"sessionID":"ses_abc123","part":{"tool":"read","state":{"status":"completed","title":"src/app.ts"}}}
{"type":"tool_use","timestamp":1719830402500,"sessionID":"ses_abc123","part":{"tool":"edit","state":{"status":"completed","title":"src/app.ts"}}}
{"type":"text","timestamp":1719830404000,"sessionID":"ses_abc123","part":{"type":"text","text":"Added validation and updated the tests. All 12 tests pass."}}
{"type":"step_finish","timestamp":1719830404100,"sessionID":"ses_abc123"}

Event `type`	What it signals
`step_start`	The agent began a new step of work
`tool_use`	A tool finished running (a file read, an edit, a command, and so on)
`text`	The agent produced a chunk of its written response
`step_finish`	A step of work completed
`error`	Something went wrong during the task

Consuming it in a script is a matter of reading line by line. To pull just the final written answer with jq:

100xprompt run --format json "Summarize this branch" \
  | jq -r 'select(.type == "text") | .part.text'

The JSON stream is line-delimited (one object per line), not a single JSON array. Parse it incrementally - read a line, parse a line - rather than waiting for the whole output to become valid JSON.

Use cases

CI checks

Run a review or a policy check on every pull request. Pipe the diff into run --format json, parse the result, and fail the build or post a comment based on what 100xprompt found.

Batch tasks

Apply the same change across many files or repositories. Loop over inputs and either call run per item or fan sessions out in parallel with the client.

Scheduled maintenance

Wire run into a cron job to keep dependencies current, refresh generated code, or sweep for issues on a schedule - unattended.

Embedded automation

Use the official client to put 100xprompt behind a button in your own tools - trigger a session, stream progress, and surface the result in your product.

Check a pull request in CI

Suppose you want 100xprompt to review every pull request and gate the merge on what it finds. Three steps: capture the diff, run the review headlessly, act on the result.

Capture the change

Produce the diff you want reviewed - for example, the changes on the current branch compared to your main branch.

git diff origin/main... > /tmp/change.diff

Run the task headlessly

Feed the diff into 100xprompt and ask for a structured review, capturing the JSON stream.

100xprompt run --format json -f /tmp/change.diff \
  "Review this diff for correctness bugs. List any you find." \
  > /tmp/review.jsonl

Act on the result

Parse the events, extract the written verdict, and let your pipeline decide what to do - comment on the PR, annotate the build, or gate the merge.

jq -r 'select(.type == "text") | .part.text' /tmp/review.jsonl

Tips and limits

Keep automated runs unattended

Interactive runs pause to ask for approval on consequential actions. When automating, design tasks and choose an agent whose permissions match what you’re comfortable letting run without a human in the loop - and scope each task narrowly so it stays predictable.

Prefer JSON for anything a machine reads

The default output is formatted for a person watching a terminal. Whenever a script, CI job, or another program consumes the output, use --format json so you get stable, parseable events instead of styled text.

Continue a session for multi-step flows

Use --continue or --session to send a follow-up prompt into an existing session, so context from the earlier task carries forward instead of starting cold each time.

Fan out for throughput

Independent tasks don’t need to share a session. With the client, create one session per unit of work and run them in parallel to process large batches quickly.

Workflows: compose repeatable, automated sequences of 100xprompt tasks.
Terminal: the interactive experience these headless runs are built on.
Quickstart: go from zero to your first shipped change.

Workflows

Compose repeatable, automated sequences of 100xprompt tasks.

Terminal

The interactive experience these headless runs are built on.

Quickstart

Go from zero to your first shipped change in five minutes.

​Understand the shape

​Pick an entry point

​Reference the run flags

​Parse the JSON event stream

​Use cases

CI checks

Batch tasks

Scheduled maintenance

Embedded automation

​Check a pull request in CI

​Tips and limits

​Related

Workflows

Terminal

Quickstart

Understand the shape

Pick an entry point

Reference the `run` flags

Parse the JSON event stream

Use cases

Check a pull request in CI

Tips and limits

Related