deep-horizon

A deterministic, human-authored horizon — a short list of open gaps plus a session log — shared across AI agent harnesses, injected at the start of every new session.

The horizon is what the human wants and does not yet have: at most 5 open gaps, each one line, written by the agent only after the human agrees. Nothing here is a task list; gaps sit open for weeks and that is the normal case. Every harness reads and writes the same store, so the aim survives between sessions and between tools.

Install

CLI first, adapter second. The binary must be on PATH before any adapter is configured; hooks fail open (they inject nothing) when the bin is missing.

npm install -g deep-horizon

The registry tarball ships dist/ as packed, so no build step and no lifecycle script runs on install — the npm >= 12 install-scripts protection is irrelevant on this route.

After installing, wire the harnesses — install writes the hook config itself (parse, merge, validate, timestamped backup; it refuses loudly rather than blind-write an unrecognized shape), and doctor verifies the result:

horizon install --harness zcode --harness hermes
horizon doctor

From a checkout instead (hacking on the adapters): build before installing. On npm >= 12 the install-scripts protection blocks this package's prepare (the build) on path installs, and the --allow-scripts remedies npm's own warning suggests still block for path installs — an unbuilt clone installs bins that crash with ERR_MODULE_NOT_FOUND for dist/cli.js. (npm pack is unaffected; prepare still runs there.)

git clone https://github.com/andrepontesmelo/deep-horizon
cd deep-horizon
npm install && npm run build
npm install -g .

A folder install is symlinked, so the global bins run this checkout's dist/ — build in the clone and the install is whole.

Status: this package ships the CLI core (horizon), the horizon-inject composer, and adapters for every harness below (Claude Code has no npm artifact — its settings block is the adapter). After the CLI is on PATH, horizon install --harness zcode|hermes wires the adapter configs for you and horizon doctor verifies the wiring — see Wiring below.

CLI

Run horizon inside a project; the store lives in .horizon/ (found upward, like git finds .git). horizon init creates it.

usage: horizon [--cwd <path>] [--json] [--harness <name>] [--session <id>] [--origin <human|agent-proposed>] <show|about|add|close|amend|detail|log|session-end|init|doctor|install> [...]

commands:
  show                      print open gaps (id + two spaces + text)
  about                     print the about line
  about "<text>"            set or replace the about line (what this project is)
  about --clear             unset the about line
  add <id> "<text>"         append a gap under a caller-chosen slug id; prints the id (--detail "<text>" attaches details)
  close <id>                remove a gap; frees a slot
  amend <id> "<text>"       rewrite a gap's text in place
  detail <id>               print a gap's details
  detail <id> "<text>"      set or rewrite a gap's details (2048 code points max)
  detail <id> --clear       remove a gap's details
  log [--limit N]           print session records, newest first
  session-end --harness <name> --session <id> [--summary "<text>"] [--store <dir>] — once per (harness, session); a repeat is a silent no-op
  init                      create .horizon/ in --cwd
  doctor [--harness <name>] read-only wiring check per harness (zcode, hermes; both by default) — one PASS/FAIL line per check with the fix hint; exit 0 all-pass, 1 any FAIL
  install --harness <name>  wire a harness's global config (zcode, hermes; repeat the flag or comma-separate); parse → merge → validate → backup → atomic write, idempotent

A gap's title is one line; it may also carry optional details — the extended context (what, why, where it came from) that must not crowd the line. Details may be multi-line, at most 2048 Unicode code points, set at creation with add --detail "<text>" or later with horizon detail. They are never injected: the injected horizon carries the one line only, plus a pointer that horizon detail <id> retrieves the rest on demand.

Only the human closes a gap. The agent proposes — horizon add / horizon close run only after the human says yes. Gap ids are chosen, not minted: horizon add plant-photo-lookup "A person can hand a photo to the app and get the plant named." — a slug of 3–40 lowercase letters, digits, and hyphens, starting with a letter. An id is never reused, even after its gap closes, so a name always means the same gap for the life of the project. The about line is one human-authored line saying what this project is (gaps say where the work is heading); when set, it is injected ahead of the horizon block. Store files: .horizon/gaps.json (the open gaps, the retired ids of closed gaps, and the about line), .horizon/sessions.jsonl and .horizon/closes.jsonl (append-only history).

The store and git

gaps.json is the shared truth: commit it. The append-only logs (sessions.jsonl, closes.jsonl, hooks.log) are machine-local by design — gitignored by the .gitignore every store carries, never merged, because concurrent append-only logs would spend their lives in merge conflicts for no cross-machine value. The trade, stated once: what is open or closed travels with the repository; when it happened and in which session stays on the machine where it happened.

Git worktrees are the corollary, not a problem: a committed gaps.json does not fork the store, it branches it — each worktree checkout rides its branch like any other file, and merging the branch home reconciles the gaps with it. A worktree's sessions.jsonl is that checkout's diary and stays there. horizon init writes the nested .gitignore that implements all of this; the pattern this repo's own root .gitignore uses (ignore .horizon/*, re-include gaps.json, .gitignore, .gitattributes) is the canonical one to copy.

The adapter wire interface

Every harness's glue is the same two calls, and neither discovers a store on its own. horizon-inject --harness <name> --cwd <dir> prints the text to inject — empty output means silent. With --json the answer is total: one JSON line, {"text": <string>, "store": <string|null>} — the composed text plus the store directory the composer already resolved (null when no store was found). The close hooks hand that store back, so teardown never re-discovers it: horizon session-end --harness <name> --session <id> --store <dir> (without a store the command still works, discovering from --cwd; a path that does not exist is a silent no-op).

Wiring: horizon install, horizon doctor

Two adapters ride global config surfaces — ZCode's ~/.zcode/cli/config.json and Hermes' ~/.hermes — and horizon install applies them so nobody has to hand-edit JSON:

horizon install --harness zcode      # repeat the flag or comma-separate: --harness zcode,hermes
horizon install --harness hermes

ZCode: the config is parsed, merged, validated, backed up (config.json.bak-pre-horizon-<timestamp> alongside), and written atomically — never a blind write. A config that does not parse, or a hooks shape install does not recognize, is a loud refusal (exit 2, fix by hand): an unparseable config disables the whole file in ZCode, so writing over one is the one unrecoverable move. The merge writes the block documented in the ZCode section below (SessionStart matcher startup|resume, PreToolUse pre-execute), preserves every foreign key, replaces only deep-horizon's own entries (matched by a command naming deep-horizon), and leaves Stop untouched. Global config only: project hooks are trust-gated and double-fire once trusted when both scopes declare them — exactly one surface per machine. Hermes: the plugin files are copied to ~/.hermes/plugins/deep-horizon/ (byte-identical files skipped, stale __pycache__ removed) and ~/.hermes/config.yaml gains deep-horizon in plugins.enabled — appended last, backed up, nothing else reordered; a yaml install cannot confidently read is refused, not guessed at. Re-running an install changes nothing when already wired (and takes no backup when nothing will be written); upgrading is npm i -g deep-horizon@latest && horizon install --harness zcode --harness hermes && horizon doctor — the merge is the migration, there is no config migration machinery.

horizon doctor is the read-only twin: per harness, one PASS/FAIL line per check with the fix hint, exit 0 when everything is wired, 1 when something is not. It checks the bins on PATH, the config's presence and parse, both ZCode hooks (a missing PreToolUse is the F3-class "shipped but not wired" state — the check names it and the fix), and for Hermes the plugin files, the plugins.enabled entry, and the shims. Absent and corrupt configs are FAIL lines, never a crash.

horizon doctor                       # both harnesses; --harness zcode narrows

Per-harness setup

1. DeepSeek Harness (DSH) — reference implementation

Install from a built checkout, CLI first:

git clone https://github.com/andrepontesmelo/deep-horizon
cd deep-horizon
npm install && npm run build    # build in the clone first — see Install
npm install -g .                # the CLI, from this clone
npm pack                        # the plugin tgz, from the built checkout
dsh --profile <profile> --from-default-profile sdk-minimal --dump-config
dsh plugin --profile <profile> add file:/abs/path/deep-horizon-<version>.tgz

Upgrading: bump the version, npm pack, and re-run the dsh plugin add — or remove the plugin, then re-add. Re-adding an unchanged version prints "Already up to date" and silently keeps the old bits, and --dump-config cannot catch stale content.

npm pack deep-horizon (by name) packs the registry copy, not this code. The plugin add warns that deep-horizon "declares no dsh.bundle — installed as a plain dependency, not a profile layer". That is expected; the manual step it implies is the mount row below. Whether dsh plugin add npm:deep-horizon works was not probed — the tgz path is the documented one.

Mount in the profile's cordis.patch.yml:

- insert:
    - id: deep-horizon
      name: deep-horizon/dsh

then verify the wiring with dsh --profile <profile> --dump-config.

At session start (agent/session-start) the adapter arms one horizon-inject resolve — the moment the event fires, before the spawn has finished — and delivers the block at the session's first model step: the awaited agent/pre-step waterfall holds step 1 until the answer lands, so the first request already carries the block ahead of the launch prompt (session-start itself is fire-and-forget; an injection fired there, rather than armed for the first step, lands in the second step's request). A resolve that fails or times out (the 15s bin bound) leaves step 1 clean and the miss retryable. Seeded once per agent — fresh, top-level startups only (source === "startup"; resumed or compacted sessions replay their original injection, subagents never get one). The block is one of the composer's three variants: the bootstrap nudge on a project with no store or an empty one, the warm nudge when an about line is set but no gaps are, the horizon block when gaps are open (the about line prefixes it when set). A storeless launch from the home directory stays silent — $HOME is not a project.

A session launched in repo A that touches repo B mid-session is covered by a second injection path, the param trigger (tools/pre-execute): every tool call's arguments are inspected for target directories — a workdir field, the directories of file_path/path arguments, and absolute paths in command strings (which covers git -C <dir> targets). When a touched directory resolves to a repo with a horizon store, that repo's horizon is queued for the next step — once per repo per session, the launch repo's own horizon never re-fired, subagents excluded, and never for a storeless target (no store is created or offered for one; an existing but empty store still composes the bootstrap nudge, as on the startup path). Like everything else in the adapter it fails open: malformed arguments, a failed spawn, or an error queue nothing and never block the tool call.

Session end has two paths. Mid-session, on the first turn stop of a top-level session, the adapter steers the agent once to run, with the user's approval:

horizon session-end --harness dsh --session <id> [--summary "<text>"]

Omitting --summary records summary: null — a summary is never fabricated. The steer is the only path that can carry a summary, because it is the only one that can ask.

And when the session never reaches a turn stop: the DSH launcher itself registers SIGINT/SIGTERM and awaits the whole plugin tree's disposal under a 5-second force-exit budget (agent/disposed, the loop-level event, stays unawaited — but the plugin-level dispose is a different mechanism, and it is awaited). On the first Ctrl-C or SIGTERM the adapter's disposer runs inside that budget and writes, synchronously, one summary-null record per store the session served — the launch repo plus every repo the param trigger claimed (a touch the session made is a footprint worth recording even when the injection itself failed to deliver):

horizon session-end --harness dsh --session <id> --store <dir>

A second Ctrl-C force-exits past the budget and cuts the writes short; SIGHUP — a closed terminal window — has no handler at all and loses the record. A live patch-reload also unloads the plugin, but writes nothing: it is not a session end, and an early summary-null record would consume the session-end idempotency slot (first record wins) that the later user-approved steer summary needs.

2. Claude Code

npm install -g deep-horizon           # the CLI — see Install

.claude/settings.json (project-local, checked into the repo):

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          { "type": "command", "command": "horizon-inject --harness claude-code" }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "horizon session-end --harness claude-code --session \"$(jq -r .session_id)\""
          }
        ]
      }
    ]
  }
}

startup only: resumed/compacted/forked sessions replay the original injection from their transcript, so re-injecting would duplicate it. Known deliberate gap: /clear wipes the context but does not re-inject (its source is not matched by the startup-only hook) — the horizon returns next startup. Subagents are excluded structurally: the SessionStart hook does not fire for them (they get SubagentStart). SessionEnd is the only close hook proven to fire on SIGINT/SIGTERM; its stdin JSON carries the session id (jq -r .session_id reads it), and the record carries summary: null — the close hook cannot elicit model text.

3. pi

npm install -g deep-horizon           # the CLI — see Install

~/.pi/agent/settings.json:

{ "packages": ["npm:deep-horizon"] }

The extension entry point is the package's exports["./pi"] module: session_start shells out to horizon-inject and stashes the output; the first before_agent_start prompt returns it as a persistent message. Only the startup reason stashes — new, resume, fork, and reload arrive inside a running process or replay an existing horizon. The git: package specifier is proven live; npm:deep-horizon does not resolve today (no registry release), so point the specifier at the repo.

Subagent opt-out: pi has no discriminator for subagent sessions, so the adapter skips injection when HORIZON_SUBAGENT is set to a truthy value (1, true, yes). Subagent extensions should export HORIZON_SUBAGENT=1 in the child process environment. Fail-open: absent the variable, injection happens — a subagent that receives the horizon is noise, not harm.

Close: session_shutdown runs `horizon session-end --harness pi --session

npm install -g deep-horizon           # the CLI — see Install

{ "plugin": ["deep-horizon"] }

import { apply } from "deep-horizon/opencode";
export default async function deepHorizon(ctx) {
  return await apply(ctx);
}

git clone https://github.com/andrepontesmelo/deep-horizon
npm install -g deep-horizon           # the CLI — see Install
rsync -a --exclude __pycache__ deep-horizon/adapters/hermes/ ~/.hermes/plugins/deep-horizon/
rm -rf ~/.hermes/plugins/deep-horizon/__pycache__   # upgrades: --exclude keeps the OLD bytecode
# no rsync? coreutils only:
#   cp -r deep-horizon/adapters/hermes ~/.hermes/plugins/deep-horizon && \
#     rm -rf ~/.hermes/plugins/deep-horizon/__pycache__
hermes plugins enable deep-horizon
systemctl --user restart hermes-gateway   # the gateway loads plugins at start

npm install -g deep-horizon           # the CLI — see Install

{
  "hooks": {
    "enabled": true,
    "events": {
      "SessionStart": [
        {
          "matcher": "startup|resume",
          "hooks": [
            {
              "type": "command",
              "command": "\"$(npm root -g)/deep-horizon/adapters/zcode/session-start\"",
              "enabled": true
            }
          ]
        }
      ],
      "PreToolUse": [
        {
          "matcher": "Bash|Read|Edit|Write|NotebookEdit",
          "hooks": [
            {
              "type": "command",
              "command": "\"$(npm root -g)/deep-horizon/adapters/zcode/pre-execute\"",
              "enabled": true,
              "timeout": 10
            }
          ]
        }
      ]
    }
  }
}

horizon session-end --harness zcode --session <id>

node ./deep-horizon/bin/horizon.js show
node ./deep-horizon/bin/horizon-inject.js --harness <name>