config.example.toml

# nightcrow configuration example.
#
# Copy to ~/.nightcrow/config.toml and edit as needed. Every field is
# optional; omitted fields fall back to the defaults shown below.

[layout]
# The TUI's layout. The viewer has its own split, dragged from the border
# between its panels and stored in ~/.nightcrow/viewer.json — the two are
# deliberately separate, since the same percentage is a different number of
# rows on a terminal than in a browser window.
upper_pct = 55       # vertical % for the diff panel (1–99)
file_list_pct = 25   # horizontal % of upper panel for the file list (1–99)

[theme]
# The accent a session starts with, before anyone picks one. Once picked (TUI
# `<prefix> p` or the viewer's swatch) the choice is the session's and lives in
# ~/.nightcrow/viewer.json, shared by every attached TUI and open browser.
name = "yellow"      # "yellow" | "cyan" | "green" | "magenta" | "blue"

[input]
# Leader (prefix) chord. nightcrow app commands are reached tmux-style by
# pressing the leader, then a follow-up key (e.g. <leader> q to quit). Every
# other key — including Ctrl chords like Ctrl+W / Ctrl+L — passes straight to
# the focused terminal so prompt-editing keys reach the program running there.
#
# Allowed form: "ctrl+<letter>" (a single ctrl chord). Reserved no-prefix keys
# (F1..F10 select project tabs, Shift+arrows, Shift+PgUp/PgDn) cannot be
# used as the leader.
#
# Migration: the old bare-Ctrl app shortcuts moved behind the leader:
#   Ctrl+T → <leader> t   Ctrl+W → <leader> w   Ctrl+L → <leader> l
#   Ctrl+O → <leader> o   Ctrl+P → <leader> p   Ctrl+Q → <leader> q
# Fullscreen is <leader> f; Ctrl+F is now the leader itself.
# Press the leader twice (<leader> <leader>) to send the literal leader byte
# to the terminal program.
leader = "ctrl+f"    # default; one-handed, dodges tmux's Ctrl+B, terminal flow
                     # control (Ctrl+Q/S), the shell signals (Ctrl+C/D/Z), and the
                     # Ctrl chords an inner Claude Code pane uses (Ctrl+G=external
                     # editor, Ctrl+O/R/S/T/L)

[mouse]
# Capture the mouse: clicking a panel (file list, diff viewer, terminal pane)
# focuses it, clicks on terminal panes are forwarded to programs that asked
# for mouse reports (Claude Code, less --mouse, ...), and wheel scrolls move
# the pane under the pointer. While captured, select text in the outer
# terminal by holding its bypass modifier while dragging (Shift in
# xterm-family terminals, Option in iTerm2, Fn/Option in macOS Terminal.app).
# Set to false to give the mouse back to the outer terminal (plain-drag
# selection, no click forwarding).
enabled = true

[log]
enabled = true
dir = ".nightcrow/logs"   # relative paths resolve under the home directory
rotation = "daily"        # "daily" | "hourly" | "size"
max_size_mb = 10          # used when rotation = "size"
max_days = 7              # delete logs older than N days (0 = keep forever)
level = "info"            # "error" | "warn" | "info" | "debug" | "trace"
prompt_log = false        # record terminal prompt input line by line
commit_log_page_size = 100         # commits fetched per commit-log page (50..=500)
commit_log_prefetch_threshold = 25 # start the next-page fetch when the selection is
                                   # within this many rows of the loaded tail (1..=page_size)

[agent_indicator]
enabled = true            # color recently-touched files in the file list
hot_window_secs = 15      # seconds within which a file stays hot (3–3600)
auto_follow = false       # jump selection to the freshest hot file when idle

[tree]
# Read-only directory-tree navigator (enter with <leader> b). Browse the whole
# working tree and preview any file's contents in the diff pane.
respect_gitignore = true  # hide .gitignore-matched paths (target/, node_modules/, …)
max_depth = 64            # deepest directory level the tree will expand into (1..=1024)
live_watch = true         # watch expanded dirs and refresh the tree live; set false
                          # to refresh only on tree entry (large trees / odd filesystems)

# Reserve startup commands: each [[startup_command]] opens its own terminal
# pane and runs `command` immediately (via `$SHELL -lc <command>`). Panes are
# per project, so these run again for every project tab you open, not once
# per process.
# Up to 8 entries (combined with CLI --exec). 8 matches the <leader> 3–9,0
# pane-jump keys, so every startup pane is reachable by a direct key
# (<leader> 1/2 reach the file list and diff viewer; the bare F-keys select
# project tabs). This caps only the startup
# batch — open more anytime with <leader> t (panes past the eighth are reached
# via focus cycling, Shift+←/→). `name` labels the tab; when omitted the
# command text is used. With no [[startup_command]] entries, nightcrow opens a
# single empty shell.
#
# [[startup_command]]
# name = "Claude"           # optional tab label; falls back to the command text
# command = "claude"        # required; must not be empty
#
# [[startup_command]]
# command = "cargo test --watch"
#
# A pane may hand itself to a plugin (see [[plugin]] below) by naming one. Only
# panes that name a plugin are ever visible to it — everything else, including
# your plain shells, stays untouched:
#
# [[startup_command]]
# name = "Claude"
# command = "claude"
# plugin = "recovery"       # optional; omitted means no plugin sees this pane

# External plugin processes. nightcrow launches each enabled entry and speaks
# its protocol; it knows nothing about what the plugin is for, so the same
# section fits any provider or tool.
#
# Nothing here runs unless you both add an entry AND set enabled = true, and a
# plugin can only act on panes whose [[startup_command]] named it — unless you
# also set watch_on_signal, described further down.
#
# The bundled "recovery" plugin watches an opted-in pane for its provider's
# usage-limit message, waits for the stated reset time to pass, and then resumes
# the pane. It only waits — it does not bypass, raise, or work around any
# provider limit, and it sends nothing while a limit is in effect.
#
# Up to 8 entries; names must be unique, since that name is what a pane opts in
# with. `env` applies to the plugin process only, never to terminal panes.
#
# To let a plugin re-open an exited pane's session you must also list the flags
# it may append. nightcrow does not know what any CLI's flags mean, so it will
# not invent that permission: a flag you have not listed here cannot reach the
# pane's command line. That is what stops a plugin from quietly changing how a
# CLI asks for your approval — do not list a flag that weakens it.
# Leave it empty (the default) and the plugin can still wait and type into a
# live pane, but never relaunch one.
#
# watch_on_signal covers the pane you did not configure: you opened a shell with
# <leader> t and started a coding CLI in it by hand. nightcrow gives every pane a
# random token and puts it in that pane's environment only, so the CLI's own hook
# — a child of the CLI, a grandchild of the pane — can quote it back to the
# plugin. The plugin then asks nightcrow for "the pane this token names", and
# nightcrow checks the token really is one of its panes before handing it over.
#
# What you are turning on, precisely: a pane becomes plugin-visible once
# something running inside it has spoken to that plugin. A plain shell never
# does, so your shells stay untouched — but anything you start in a pane that
# talks to this plugin is consenting on that pane's behalf. The plugin is never
# given a list of your panes and cannot ask for one it has not been told about,
# and a pane another plugin already watches is not taken away. Leave it off if
# you want the [[startup_command]] list to be the whole of what a plugin sees.
#
# A pane taken on this way can be waited for and typed into, but never
# relaunched: nightcrow never launched a command in it, so there is nothing to
# put back. allowed_resume_flags has no effect on such a pane.
#
# [[plugin]]
# name = "recovery"                 # required; the name panes opt in with
# command = "nightcrow-recovery"    # required; found on PATH or in the plugin dir
# args = []                         # passed to the plugin verbatim
# enabled = false                   # off by default; set true to actually run it
# watch_on_signal = false           # off by default; see the paragraphs above
# allowed_resume_flags = ["--resume", "resume", "--session"]
#                                   # empty by default, which refuses relaunches.
#                                   # These three are what the bundled recovery
#                                   # plugin needs for Claude/Codex/OpenCode.
#
# [plugin.env]
# NIGHTCROW_RECOVERY_LOG = "info"

# The browser surface: renders git data as a real web page and serves the
# session's terminals. Always on — it is part of the session, not an add-on —
# so treat the bind address and password as security-sensitive.
[web_viewer]
bind = "127.0.0.1"        # loopback only by default; set "0.0.0.0" deliberately.
                          # The server speaks plain HTTP — for remote access
                          # prefer an SSH tunnel or a TLS reverse proxy.
port = 8091
# Login password. If none is set here, a random one is generated and written
# back to this line on first launch (and printed on startup) so it survives
# restarts and stays readable.
# password = "..."
# Alternatively store an Argon2 PHC hash instead of a plaintext password; it
# takes precedence over `password` when both are present.
# hashed_password = "$argon2id$v=19$m=..."