Ultrac harness

A general-purpose agent harness for Cosmic 1.

Ultrac is a general-purpose agent harness for unrestricted AI, designed to work with Cosmic 1 when a model service is configured.

Request access Read the docs

ultrac · ~/acme-apishell off

›Review the session TTL change and tell me what to run.

Reading the file before I say anything about it.

→read_file {"path":"src/session.ts"}

·export const SESSION_TTL_SECONDS = 900;

→run_shell {"command":"npm test"}

·Shell access requested — approve? [y/N] N

·denied: run_shell

TTL is 15 minutes, down from an hour. Tests did not run: you refused the shell.

Available tools

48 tools for local tasks.

The harness provides tools for files, commands, Git, network requests, memory, and task planning. Tools run on your machine with the permissions you grant.

Read files

List, read, and search files inside the workspace. read_file returns a line range so you can read large files in sections.

list_files · read_file · read_many_files · search_files · ast_search

Understand the project

Inspect the repository, identify its structure, and collect project context for later steps.

inspect_project · repo_map · repo_handbook · context_bundle

Change files

Four ways to write, from a whole file to an exact replacement to a unified diff. Every one of them declares write, so every one of them is refused until you grant it.

write_file · replace_in_file · multi_edit · apply_patch

Git, without a shell

Reading history is a separate capability from running commands, so these do not declare shell. They spawn git directly, through the hardened invocation described above.

git_status · git_worktree_summary · git_diff · git_log · git_show · git_blame · git_commit · git_push

Inspect artifacts

Hashes, strings, hex, secret patterns, and a file timeline inside the workspace. Optional file/strings when shell is granted. list_processes is host inventory, and still needs shell.

inspect_artifact · hex_dump · extract_strings · scan_secrets · file_timeline · list_processes

Run and verify

Executing anything needs shell. Planning the checks and writing the report do not, so an agent with no permissions at all can still say what should have been run.

run_shell · run_package_script · run_tests · diagnostics · verification_plan · verification_report

Carry work across turns

Track tasks and store information between sessions. Reading memory does not require write permission; writing or deleting it does.

todo_write · todo_read · memory_write · memory_read · memory_list · memory_search · memory_delete

Recall earlier sessions

Every session is saved as a transcript under .ultrac/sessions. These three are how a later run finds out what an earlier one already tried.

list_sessions · read_session · search_sessions

Delegate and extend

A bounded child agent with its own window, SKILL.md playbooks loaded on demand, a clarifying question for the user, and the HTTP client that talks to a URL you name.

task · skill · list_skills · fetch_url · ask_user

How a turn runs

Run tasks across multiple steps.

The harness can read a file, find its callers, edit, run checks and respond to failures across multiple tool steps. It stops when the model finishes, you interrupt it, or an execution or context limit is reached. Resume from a saved checkpoint when more work remains.

Queue a follow-up

Type a new message while a turn is running. It waits until the current tool call finishes, then the harness follows that message instead of the rest of the batch.

Stop a turn or exit

Press Esc to stop the current turn and return to the prompt. Press Ctrl-C to exit. Completed work remains in the session transcript.

Approve tool permissions

File writes, shell commands, and network requests require permission. You can approve a request once, approve future requests, or deny it. Denied requests are reported to the model.

Workspace trust

Repository configuration can request permissions and MCP servers. The harness requires workspace trust before accepting those settings and reports any settings it withholds.

Several jobs at once

Independent delegated searches can run concurrently. Operations that write files run sequentially.

Workspace checks for file tools

Structured file tools check canonical paths and reject outside-workspace targets. Approved shell commands run with your user account's access, so review them before allowing execution.

Resumable

Completed checkpoints are saved locally, and --continue resumes from the saved session. The harness warns if saving fails. An interrupted step may need to be run again.

Modes

Five modes with different tool sets.

Each mode sets the instructions and tools presented to the model. Plan and Review do not include file-editing tools in their advertised tool sets. Tool permissions are checked separately.

planRead, search, map, and write the steps down, with delegation, skills, memory, and one clarifying question.

reviewReview the worktree, history, and diagnostics, with verification tools and shared agent capabilities; editor tools stay out.

defaultThe working set: gather the repository on demand, then read, search, run, edit, patch, see what changed, keep a plan, delegate, and ask when the answer matters.

securityThe core plus local evidence tools and an HTTP client: hashes, strings, hex, secret scan, timeline, blame, and fetch_url.

codingUse file tools, tests, diagnostics, package scripts, and structural search to implement and verify code changes.

Install and start

Install ultrac, then start it in a repository.

You need Node.js 22.12.0 or newer. Install the public @spinalfluid/ultrac npm package, then run ultrac login to open ultrac.io and connect your approved Ultrac account. Run ultrac from the repository you want to work in.

npm install -g @spinalfluid/ultrac
ultrac login
ultrac

After login, the harness connects to ultrac.io over HTTPS. The service forwards model requests to Cosmic 1 and checks your plan limits before processing them. The CLI does not connect to the model host over SSH.

Use --provider echo for an offline dry run.