Skip to main content

Lifecycle Guide

How to start, stop, pause, recover, and update Adjutant.


States​

Adjutant has three possible states:

StateWhat it meansHow to enterHow to exit
RUNNINGOperation worker and listener are activeadjutant startadjutant stop, adjutant pause, or adjutant kill
PAUSEDSilent autonomous state; managed cron entries are removed and autonomous notifications are suppressedadjutant pause or /pauseadjutant resume or /resume
KILLEDHard stop; KILLED lockfile exists; nothing will start until explicit recoveryadjutant kill or /killadjutant startup (clears lockfile, restores crontab, starts fresh)

Check the current state at any time:

adjutant status

Or from Telegram:

/status

Normal Operation​

Start​

adjutant start

Starts the durable-operation worker, then starts the Telegram listener in the background. Starting the worker first ensures that natural-language messages do not enter the durable queue without a process available to execute them. The listener polls the Telegram API in a continuous loop and acquires a directory-based mutex (state/listener.lock/) to prevent duplicate instances.

If a KILLED lockfile exists, use adjutant startup for full recovery (see below).

Stop​

adjutant stop

Kills the listener process using its stored PID. Any in-flight response that has already started will complete; new messages will not be processed until the listener is restarted.

Restart​

adjutant restart

Stop followed by start. Useful after configuration changes or after pulling an update manually.


Pause and Resume​

Pausing is a soft stop. Use it when you want Adjutant to stop responding temporarily without triggering a full emergency shutdown.

# Pause (from terminal)
adjutant pause

# Pause (from Telegram)
/pause

# Resume (from terminal)
adjutant resume

# Resume (from Telegram)
/resume

While paused:

  • The listener process continues running and polling
  • Autonomous jobs do not run: only # adjutant: crontab entries are removed
  • Autonomous notifications are suppressed, including any stale or in-flight cron completion
  • The PAUSED lockfile at $ADJ_DIR/PAUSED controls this behaviour
  • Manual control remains available, including adjutant status, /status, and /resume

adjutant resume rebuilds enabled managed cron entries from adjutant.yaml. Unrelated user crontab entries are never changed by pause or resume. If you enable a schedule while paused, its registry entry is updated and its cron entry is restored on resume.

Both pause and resume are idempotent — calling them when already in the target state has no effect.


Emergency Kill​

Use this when something is wrong: a runaway loop, unexpected file changes, excessive resource use, or erratic behaviour.

# From terminal
adjutant kill

# From Telegram
/kill

What happens:

  1. Creates $ADJ_DIR/KILLED lockfile
  2. Terminates all Adjutant-related processes (listener, LLM backend, any background jobs)
  3. Disables cron jobs (backed up to state/crontab.backup)
  4. Logs the event and sends a Telegram notification

After a kill, nothing will start until the lockfile is cleared. This is intentional — it prevents accidental restart after an emergency.

Recovering from a kill​

adjutant startup

adjutant startup detects the KILLED lockfile, enters recovery mode, and walks through:

  1. Removing the KILLED lockfile
  2. Restoring the crontab from state/crontab.backup
  3. Re-syncing the schedule registry to crontab
  4. Starting the Telegram listener
  5. Sending a Telegram notification confirming recovery

Note: adjutant start (without startup) will refuse to start if a KILLED lockfile is present — use adjutant startup for full recovery.

KILLED vs PAUSED​

PAUSEDKILLED
Listener still runsYesNo
Manual messages processedYes; autonomous notifications remain suppressedNo
Managed cron entriesRemoved; restored from enabled registry entries on resumeEntire crontab backed up and removed; recovery restores it
Autonomous notificationsSuppressedSystem stopped
Requires explicit recoveryadjutant resumeadjutant startup (will not auto-recover)
SeverityLow — routine useHigh — emergency only

Auto-Start on Login​

To start Adjutant automatically when you log in to your Mac:

adjutant startup

This installs a LaunchAgent plist at ~/Library/LaunchAgents/com.adjutant.telegram.plist. The listener will start on every login without manual intervention.

To remove the LaunchAgent:

launchctl unload ~/Library/LaunchAgents/com.adjutant.telegram.plist
rm ~/Library/LaunchAgents/com.adjutant.telegram.plist

Update​

adjutant update

Self-update flow:

  1. Checks the current VERSION against the latest GitHub release tag
  2. If already up to date, exits with no changes
  3. If an update is available:
    • Backs up the current installation
    • Downloads the release tarball
    • Rsyncs new files into place (your personal files — adjutant.yaml, .env, identity/, knowledge_bases/ — are never overwritten)
    • Runs adjutant doctor to verify the updated installation

After updating, restart the listener to pick up any script changes:

adjutant restart

Doctor​

adjutant doctor

Checks that required tools are installed (bash, curl, python3, and your configured LLM backend binary), credentials are present in .env, identity files exist, and the listener state. Does not modify anything — read-only diagnostic.


Lifecycle State Machine​

          adjutant start
│
▼
┌─────────────┐
│ RUNNING │◄──── adjutant restart
└─────┬───────┘
│
┌────────┴────────┐
▼ ▼
adjutant pause adjutant kill /kill
│ │
▼ ▼
PAUSED KILLED
│ │
▼ ▼
adjutant resume adjutant startup
│ │
▼ ▼
RUNNING RUNNING

Recovery from KILLED requires adjutant startup -- not adjutant start. adjutant start will refuse if a KILLED lockfile is present.


Active Operation Tracking​

When a pulse or review is running, Adjutant writes a marker file at state/active_operation.json. This allows external clients (like the web dashboard) to observe the running state without holding open an HTTP connection.

{
"action": "pulse",
"started_at": "2026-03-18T21:30:00+00:00",
"pid": 12345,
"source": "cron"
}

The marker is created before the operation starts and removed when it finishes (in a finally block, so it's cleaned up even on failure).

Source values​

SourceMeaning
cronTriggered from CLI (adjutant pulse) or crontab
telegramTriggered via /pulse or /reflect → /confirm in Telegram
adjutant-webTriggered from the web dashboard (spawns adjutant pulse)

Staleness detection​

If the marker is older than 30 minutes and the recorded PID is no longer alive, it is treated as stale and automatically cleaned up. This handles edge cases like SIGKILL or power loss.


Post-Operation Notifications​

After a successful pulse or review, Adjutant sends a Telegram notification with a summary of results. This happens automatically regardless of how the operation was triggered (CLI, crontab, adjutant-web, or Telegram).

The notification includes:

  • Which KBs were checked
  • Any issues found
  • Whether the findings were escalated
  • Where the trigger came from

Notifications use the daily budget system (notifications.max_per_day in adjutant.yaml, default 3). If the budget is exhausted, the notification is silently skipped. The pulse/review itself still completes normally.

Note: when triggered from Telegram via /pulse, the notification is redundant since the results are already sent as a chat reply. Both are sent, but the daily budget prevents excess.


Morning Brief​

The morning brief is a proactive daily summary designed for the user, not for system health. It combines:

  • Current priorities from heart.md with KB status updates
  • Deadlines in the next 7 days from all KBs
  • Unprocessed insights from insights/pending/
  • Overnight changes since the last pulse
# Run from terminal
adjutant brief

# Run from Telegram
/brief

# Schedule via crontab (e.g., every weekday at 07:30)
# In adjutant.yaml schedules:
# - name: morning-brief
# schedule: "30 7 * * 1-5"
# script: "adjutant brief"
# enabled: true

The brief uses kb query-all internally to query all KBs in parallel, making it significantly faster than a sequential pulse. Output is sent as a single Telegram notification, kept under 800 characters for phone readability.

The brief differs from pulse in purpose: pulse is a system-level health check that writes to journal and escalates issues. The brief is a user-facing daily planner that tells you what to focus on today.


Self-Assessment​

The self-assessment is a weekly introspection cycle where Adjutant evaluates its own effectiveness and proposes improvements. It runs through prompts/self_assess.md and:

  1. Reviews the past week's journal entries
  2. Analyzes notification outcomes (which were useful, which were noise)
  3. Compares heart.md priorities against actual activity
  4. Evaluates signal-to-noise ratio, coverage, and timing
  5. Proposes specific changes to priorities, notification frequency, and KB query patterns
# Run from terminal
adjutant self-assess

# Run from Telegram (any of these work)
/self-assess
/selfassess
/assess

# Schedule via crontab (e.g., every Sunday at 20:00)
# In adjutant.yaml schedules:
# - name: weekly-self-assess
# schedule: "0 20 * * 0"
# script: "adjutant self-assess"
# enabled: true

Safety: The self-assessment never modifies identity/soul.md or identity/heart.md directly. All proposed changes are written to insights/pending/self-assessment-YYYY-WNN.md for the user to review and approve. This keeps the human in the loop for any behavioural changes.


Autonomy Configuration​

Adjutant supports graduated autonomy levels via the autonomy section in adjutant.yaml:

autonomy:
level: 2 # 1=notify-only, 2=suggest+approve, 3=act+notify, 4=autonomous
auto_approve:
- kb_data_refresh # Actions that don't need approval at level 3+
- memory_digest
require_approval:
- heart_update # Actions that always need approval, regardless of level
- notification_rule
LevelBehaviour
1Notify-only — never act without explicit instruction
2Suggest and act on approval (default) — proposes changes, waits for confirmation
3Act and notify — performs actions autonomously, then tells you what it did
4Fully autonomous — acts silently, logs only

The auto_approve list specifies actions that can proceed without user approval at level 3 and above. The require_approval list specifies actions that always need explicit approval, regardless of autonomy level.


Parallel KB Queries​

Pulse now uses kb query-all to query all registered KBs concurrently instead of sequentially. With 6 KBs at ~70 seconds each, this reduces pulse wall time from ~7 minutes to ~80 seconds.

The kb query-all command:

  • Reads all KB entries from knowledge_bases/registry.yaml
  • Uses each KB's query_hint field for targeted questions
  • Falls back to a generic status query if no hint is set
  • Runs all queries via asyncio.gather() for maximum concurrency
  • Returns a combined result with one section per KB
# Query all KBs with default hints
adjutant kb query-all

# Override with a custom question for all KBs
adjutant kb query-all -q "What deadlines are in the next 7 days?"

Cross-KB Intelligence​

The kb cross-query command enables multi-domain synthesis — asking questions that span multiple KBs:

adjutant kb cross-query "Do I have any scheduling conflicts?" --kbs ixda,fagkomite

This:

  1. Queries the specified KBs in parallel
  2. Feeds all responses into a synthesis prompt
  3. Returns a unified answer that identifies cross-domain connections and conflicts

Use this when you need insights that no single KB can provide alone.