Background sessions

A background session is a Syntic Code run that keeps going after you close the terminal. Start a long job, go to lunch, and check on it later from any terminal.

Start one

syntic --bg "upgrade the test suite to the new fixtures API and get it green"

Started background session 08e14168
  working in .syntic/worktrees/bg-7297a7d6 (your checkout is left alone)
  syntic logs 08e14168 -f    follow its output
  syntic attach 08e14168     continue it here
  syntic stop 08e14168       stop it

Each background run works in its own git worktree, so it never touches the files you are editing. --bg implies -p, so everything on Scripting & CI applies.

From inside a session, /background <task> (or /bg) hands a task to a background session that starts from the current conversation, and /branch --bg <task> does the same with a copy of it.

Check on it

An id can be shortened to any unique prefix: syntic logs 08e1.

States

When it needs you

A background run never waits for an answer and never guesses. If a tool call needs approval, the call is refused, recorded, and the run ends as needs input. syntic sessions shows what it asked for; syntic attach <id> lets you answer and carry on. To avoid this, give the run the permissions it needs up front (--allowed-tools, --permission-mode acceptEdits).

How a background run is kept apart

• Its own worktree. In a git repository, a new run gets a worktree named bg-<id> under .syntic/worktrees/, unless you chose one yourself with -w. Inside that worktree, edits, shell writes and git commands aimed at your main checkout are refused, so the run cannot touch the files you are working on.
• Outside git. With no repository there is no worktree to make, and the run works in the folder you started it in. Avoid editing the same files while it runs.
• Same options as -p. --model, --permission-mode, --allowed-tools and the other run options apply to the background run. A respawned run keeps the original run’s model, permission and tool options.
• Survives restarts. If the computer restarts or the process dies, the run shows as interrupted. syntic respawn <id> continues its saved conversation under the same id and appends to the same log.

When it is done, review the worktree’s branch and merge it like any other branch (Worktrees).

Examples

# a long refactor, with edits allowed and the test runner pre-approved
syntic --bg "move all date handling to the new time library and keep the tests green" \
  --permission-mode acceptEdits --allowed-tools "Bash(npm test:*)"
 
# follow it, then step in
syntic logs 08e1 -f
syntic attach 08e1
 
# clean up runs older than a week
syntic sessions --prune --older-than 7

See all your background sessions

syntic agents opens a full-screen dashboard of every background session across your projects, where you can attach, read logs, stop runs and prune old ones. Inside a session, ← on an empty prompt (or /tasks) shows this session’s subagents and background work. Both are covered on The agents view.

Troubleshooting