Repository navigation
Terminal and MCP
This page is for people who work in a terminal. You do not need it to use Night Shift.
The most common use: let an agent in your terminal, such as Claude Code, read and change your flows, start runs, and answer Gates. The nightshift command gives it the tools for that over MCP. You can also read and save flows yourself with nightshift flows.
Night Shift must run on the same computer.
-
Get the
nightshiftcommand. See Get the command. -
Add Night Shift to Claude Code:
claude mcp add nightshift -- nightshift mcp
-
Start Claude Code in the folder of your project, and ask it, for example: "List my flows, and add a Gate before the email step of weekly-brief."
The agent checks each flow before it saves it. Each save is a new revision of the flow, so you can restore an earlier one in the editor.
Other agents, such as Codex, work too. Give them the command nightshift mcp as an MCP server.
| Tool | What it does |
|---|---|
list_projects, list_flows, get_flow
|
Read the projects and their flows. |
list_profiles, list_tools, list_skills
|
Look up the names that a node may use. |
check_flow, save_flow
|
Check a flow, and save it when it has no errors. |
start_run |
Start a saved flow with its inputs. |
list_runs |
The newest runs, by status and since a time. Each with its cost and pull request. A test run says which nodes it pinned and skipped. |
get_run |
One run: its status, cost, pull request, steps, why it failed, and its report. A test run says so, and so does each step whose node did not run. |
stop_run |
Stop a run now, or after the step that runs now. |
needs_me |
The Gates that wait for you, in every project, with the question and the options. |
answer_gate |
Answer a Gate with one of its options and a note. The run continues. |
search_knowledge |
Search the project's knowledge by keyword, and by meaning when Ollama runs. Gives the best files, each with its path, section, and an excerpt. |
read_knowledge |
Read one file of the knowledge by its path. |
The knowledge files are also MCP resources.
- The Docker image has
nightshifton its PATH. - From a clone, run
bun <clone>/apps/server/src/cli.tswhere this page saysnightshift.
To make it short, run this once in the clone, or add the alias to your shell profile:
alias nightshift="bun $PWD/apps/server/src/cli.ts"From a clone, put the full bun command after -- in claude mcp add.
Run these commands in the folder of a project. They use the project of the current folder. Night Shift checks each save and keeps it as a new revision of the flow.
nightshift flows list # name, steps, errors, description
nightshift flows get weekly-brief > brief.json # the flow as JSON
nightshift flows save weekly-brief brief.json # or from stdin, and prints its problems
nightshift flows export weekly-brief --out ./ # a file to import elsewhere
nightshift flows import weekly-brief.json # a new flow, and a taken name gets a suffix
nightshift flows revisions weekly-brief # who saved what, newest first
nightshift flows revision weekly-brief <id> # one earlier revision as JSONAn import gives each agent of the flow to one of your profiles. To choose another profile, add --agent claude-code:opus=reviewer.
Usage:
nightshift flows list [--json] The flows of the project: name, steps,
errors and description, one per line.
nightshift flows get <name> [--out <file>] The flow as JSON.
nightshift flows save <name> [<file>] Save the flow of the file (else of stdin)
as <name>: a new flow, or a new revision.
nightshift flows export <name> [--out <file or folder>]
The flow as a file to import elsewhere.
nightshift flows import <file> [--name <name>] [--agent <agent>=<profile>]...
Save the flow of the file as a new flow.
A name the project has gets a suffix.
Prints the name it got. One of your
profiles takes each agent the flow names:
the same harness and model, else the same
harness, else your first profile. Prints
each choice.
nightshift flows revisions <name> [--json] The revisions of the flow, newest first.
nightshift flows revision <name> <id> [--out <file>]
One revision of the flow as JSON.
Options:
--project <id, name or folder> The project. Default: the project of this folder.
--daemon <address> Where Night Shift runs. NIGHTSHIFT_DAEMON_URL,
default http://localhost:$PORT.
--agent <agent>=<profile> With import: the profile for one agent of the flow,
for example claude-code:opus=reviewer. Repeat it
for each agent you choose.
--keep-agents With import: keep the agents the flow names.
To start a flow from GitHub Actions, n8n, Zapier, or a script, send a webhook to a schedule. See Webhooks.
The other commands run a Host and pair computers. Computers and Hosts tells when you need them.
Night Shift
Usage:
nightshift serve [options] Run Night Shift on this computer.
nightshift join <host-address> [--guest] Pair this computer with a Host.
nightshift pair <code> [--yes] Allow a computer to pair with this Host.
nightshift merge [--dry-run] [--yes] Merge the Personal of this computer into
the Personal of its home Host. It shows
what moves and asks first.
nightshift leave [--yes] Leave the home Host of this computer. The
Host keeps everything. This computer keeps
its own Personal. It asks first.
nightshift admin --email <email> Set how the Host admin signs in from
another computer. --reset-two-factor
also turns two-factor sign-in off.
nightshift mcp [--project <project>] Serve the flow tools to an agent in a terminal
(MCP on stdio). Night Shift must run here.
Claude Code: claude mcp add nightshift -- nightshift mcp
nightshift flows <action> [options] Read and save the flows of a project:
list, get, save, export, import,
revisions, revision.
nightshift flows --help for the details.
nightshift health [--restart] Exit code 0 when Night Shift runs here, else 1.
--restart stops a Night Shift that does not
respond, so that its service manager starts it
again. --data-dir as for serve.
Options of serve (each has an environment variable too):
--port <port> The port. PORT, default 3000.
--data-dir <folder> Where the database and the run history go. NIGHTSHIFT_DATA_DIR.
--host-address <url> Be a Host at this https:// address. Repeat it for each
address, in the order other computers try them.
NIGHTSHIFT_HOST_ADDRESSES (comma-separated).
--listen <ip> Where a Host listens. NIGHTSHIFT_LISTEN, default 0.0.0.0.
Use 127.0.0.1 behind Tailscale Serve, a tunnel or a proxy.
--tls-port <port> The https:// port with NIGHTSHIFT_TLS_CERT and _KEY.
NIGHTSHIFT_TLS_PORT, default the port + 443.
--web <folder> Serve the web UI from this folder. NIGHTSHIFT_WEB_DIR.
--require-two-factor People who sign in from another computer must use
two-factor sign-in. NIGHTSHIFT_REQUIRE_TWO_FACTOR=on.
The auth secret is BETTER_AUTH_SECRET, else the file BETTER_AUTH_SECRET_FILE,
else BETTER_AUTH_SECRET in NIGHTSHIFT_SECRETS_DIR or systemd's credentials,
else one Night Shift makes once in the data folder.
This wiki comes from docs/wiki/ in the repository. To change a page, open a pull request there. An edit made here is lost at the next publish.
Start here
Use Night Shift
Reference
Repository