Force documentation

How to install Force, find your way around the cockpit, and drive sessions from a script or another agent. Everything here is something Force does today.

Install

One line, as your user. No root, no packages. Linux on x86-64; it needs only curl or wget.

$ curl -fsSL https://useforce.cc/install.sh | sh

It unpacks into ~/.local/share/force and brings its own tmux 3.4 (and its own Python 3.12 when the system one is older than 3.11). It puts force in ~/.local/bin and on your PATH for bash, zsh and fish, starts its two background services (systemd user units; without systemd, force starts them itself) and, on a desktop, installs the icon font.

Options go after sh -s --:

$ curl -fsSL https://useforce.cc/install.sh | sh -s -- --no-fonts

`--no-fonts`	Don't install the icon font.
`--no-services`	Don't create or start the background services; `force` still works.

Force doesn't install the agents. For Claude Code:

$ curl -fsSL https://claude.ai/install.sh | bash

First run

$ force                 # on the computer you sit at
$ ssh -t devbox force   # or on a server, over ssh

force opens with a shell session. + new at the bottom of the sidebar starts an agent session (Claude Code or OpenCode) or another shell. Any terminal works: Force paints its own theme, so there's no profile to set up. In an agent, Alt+Enter or Ctrl+J starts a new line.

A short intro plays when you attach; any key skips it. force --no-intro skips it once, force settings set intro false for good.

The cockpit

The sidebar on the left lists every session on the machine, the agent you picked fills the rest, and a header above it shows the session's name, agent, model, effort and permission mode. Sessions you aren't looking at that need you or have finished show as counts at the top right.

States

Each session's bar and icon in the sidebar show its state. It comes from the agent itself (its status files and API), not from reading the screen.

needs you	A permission prompt, a question or a plan approval is waiting.
working	The agent is running.
your turn	Finished since you last looked at it.
idle	Finished, already seen.
stale	Idle for more than 12 hours (`staleAfterHours`).
down	The agent process isn't running; restart it from the menu (`x`).
outdated	Runs an older agent version; upgraded by itself once idle for 10 minutes and off screen.

Plan limits

While Claude Code sessions run, the bottom of the sidebar shows your plan's five-hour and weekly windows with their reset times, amber from 70% and red from 90%. The numbers come from Claude Code's status line and update with every reply in any Force session.

Keys and the menu

Ctrl+Space opens the Force menu with every action and its letter: press the letter or click the item, Esc closes it. Ctrl+\ and the ? controls button in the header open the same menu. There is no prefix key, so the agent never gets your keys by mistake.

`j`	Jump to a session: type part of its name, `Enter` jumps.
`Tab`	Back to the session you were in before.
`h`	Switch host: this machine or another one (also a click on the host name).
`n`	New session: agent or shell, name, folder.
`t`	New shell on this host, in the sidebar like a session.
`r`	Rename it (tmux, agent and Remote Control name; applied when idle).
`f`	Move it to another folder, keeping the conversation and memory.
`K` `J`	Move it up or down in the sidebar.
`x`	Restart it, same conversation.
`u`	Upgrade it to the newest agent version now.
`a` `A`	Archive it; open the archive (`Enter` restores, `d` deletes).
`d`	Delete it for good (asks first).
`e`	Restart all sessions, busy ones once idle; for example after changing `~/.claude/settings.json`.
`b`	Hide or show the sidebar.
`H`	Health check (`force doctor --fix`).
`q`	Quit this terminal. Sessions keep running.

Without the menu

`Alt`+`PgUp` `Alt`+`PgDn`	Previous and next session, in every terminal.
`Alt`+`1`…`9`	Session 1 to 9 (Tilix and Terminator keep these for their own panes).
Click	A sidebar row switches to it; + new and archived open their dialogs.

To copy, drag to select and right-click: it goes to the clipboard of the computer you sit at, in any terminal and over ssh. The mouse wheel scrolls.

Sessions

Each session runs in tmux on the machine, not in your terminal window. Close the terminal, lose the connection or reboot: it comes back with its conversation, and one that crashes is restarted (up to three times in ten minutes).

$ force new                          # named after your first message
$ force new api --cwd ~/src/api      # or name it yourself
$ force new logs --kind shell
$ force rename api api-v2
$ force move api-v2 ~/src/api-v2     # another folder, same conversation
$ force archive api-v2               # stop and hide; force unarchive brings it back
$ force delete api-v2 --yes          # for good; the agent's own transcript stays

Claude Code sessions also appear in the Claude app under their Force name (Remote Control), so the name is the same in Force, in Claude and on your phone.

Bringing in sessions you already have

force import lists the Claude Code sessions Force doesn't manage yet: running ones in any terminal and older stopped ones. force import ID (or a prefix of six or more characters) takes one over with its conversation: a running one once it is idle, a stopped one resumed in its folder.

Other machines

Add a server you reach with ssh (key login), and its sessions are one click away from your laptop's. Force installs itself there if it's missing.

$ force host add devbox                 # ssh target defaults to the name
$ force host add gpu me@10.0.0.7
$ force host list
$ force host upgrade devbox
$ force host remove gpu

Switch with the host name at the bottom of the sidebar, h in the menu, or force --remote devbox. A host that can't be reached shows as offline and reconnects by itself. Session commands act on the host the terminal is showing.

Notifications

Give Force one command and it runs it when a session needs you, finishes or stops. It runs through sh -c, so anything works: ntfy, your own push server, a desktop notification.

$ force settings set notifyCommand \
    'curl -d "$FORCE_MESSAGE" ntfy.sh/my-force'
$ force settings set notifyCommand 'notify-send Force "$FORCE_MESSAGE"'
$ force notify-test needs-you         # or finished, down

The command gets these variables:

`FORCE_MESSAGE`	A ready-made line: the session's name and what happened, like `api: finished`.
`FORCE_EVENT`	`needs-you`, `finished` or `down`.
`FORCE_SESSION`	The session's name.
`FORCE_KIND`	`claude`, `opencode` or `shell`.
`FORCE_HOST`	The machine it runs on.
`FORCE_STATE`	Its state now.
`FORCE_VIEWED`	`1` if you were looking at it, else `0`.

Scripts and agents

Anything that runs a shell can drive Force: a script, a cron job or another agent. Use these instead of tmux send-keys: they find the right pane and never type into an open approval dialog.

See what is running

$ force list --json        # every session: name, state, kind, folder, model, limits…
$ force explain api        # why it shows its state, and its last screen rows
$ force read api --lines 120

States in scripts: needs-you, working, your-turn, idle, stale, starting, down, shell.

Hand a session work

$ force prompt api "add a /health endpoint" --wait --timeout 600
$ git diff | force prompt api -        # "-" reads the prompt from stdin
$ force wait api --until your-turn
$ force keys api enter                 # answer a dialog: enter esc tab up down …
$ force keys api --literal 2

prompt refuses a session that needs you: read its screen and answer with force keys first. A timeout doesn't prove nothing was sent, so force read before you retry.

Report from a script in a shell session

$ force status working --summary "building the image"
$ force status needs-you --summary "approve the deploy?"
$ force status your-turn               # holds until someone looks
$ force status idle

Without a report, a shell session shows working while a program runs and your turn when it ends.

Let an agent run Force

force skill prints a short guide written for agents. Point Claude Code or OpenCode at it and it can start sessions, hand them work and collect the answers.

Settings

Settings live in ~/.config/force/settings.json, which holds only what you change.

$ force settings                       # --all includes the advanced ones, --json
$ force settings set animations subtle
$ force settings unset animations
$ force settings edit

Key	Default	What it does
`notifyCommand`	off	Runs when a session needs you, finishes or stops (above).
`animations`	`full`	`full`, `subtle` (no shimmer on working sessions) or `off`.
`intro`	`true`	The intro when you attach.
`icons`	`auto`	`auto`, `on` or `off`.
`sidebarWidth`	`29`	In columns.
`staleAfterHours`	`12`	When an idle session turns stale.
`autoUpgradeSessions`	`true`	Upgrade outdated agents by themselves…
`autoUpgradeIdleMinutes`	`10`	…once idle this long and off screen.
`layout`	`split`	`split` or `classic`.
`opencodeManaged`	`false`	Keep Force's own copy of OpenCode on the latest release.
`checkForUpdates`	`true`	The daily check for a new Force.

Updates and uninstall

A daily check shows a new release in the sidebar footer. force update installs it (--check only looks); your sessions keep running.

force uninstall asks first (--yes answers for you). It keeps your conversations, the session list and your settings; --purge removes everything, the icon font included.

When something is off

$ force doctor --fix            # health check, repairs what it can
$ force explain NAME            # why a session shows the state it does
$ force restart NAME            # same conversation; --all for every session
$ journalctl --user -u force -f # the background service's log

`~/.config/force/`	Your settings and hosts.
`~/.local/share/force/`	Force itself, the session list, and copies of archived conversations (Claude Code deletes its transcripts after 30 days).
`~/.local/state/force/`	Runtime state.

Command reference

force                                  open the cockpit   --remote NAME, --no-intro
force new [NAME] [--cwd DIR] [--kind claude|opencode|shell]
force rename OLD NEW
force move NAME up|down|DIR
force restart [NAME|--all]            force upgrade [NAME|--all]
force archive NAME                    force unarchive NAME
force delete NAME [--yes]             force list [--all] [--json]
force import [ID] [--name NAME] [--dry-run]
force host add NAME [SSH] | list | remove NAME | upgrade NAME
force prompt NAME TEXT… [--wait] [--until STATE] [--timeout SEC] [--json]
force wait NAME [--until STATE] [--timeout SEC]
force read NAME [--lines N]           force keys NAME KEY…
force status STATE [--summary TEXT]   force explain NAME
force settings [set KEY VALUE | unset KEY | path | edit] [--all] [--json]
force notify-test [needs-you|finished|down]
force update [--check]                force uninstall [--purge] [--yes]
force doctor [--fix]                  force fonts
force skill                            the guide for agents that drive Force