Little Dipper

The default agent workflow is start/checkpoint/handoff. Its compact start brief is capped at 4 KiB, with supporting context read in pages; large packets no longer prevent checkpoint or partial-handoff recording. Existing commands remain available; sessions do not automatically create cards.

Terminal workspace

Run northstar-ld tui in a linked checkout to browse and author cards and Library documents. The existing Herdr shortcut opens the same workspace. Click New/Edit or use F2/F4; click a card to preview it with a highlighted selection. F5 switches List/Board with status columns and Family/Tranche filters. Ctrl-N creates, Ctrl-E edits, Ctrl-L opens Library, and F1 shows all actions. Edits preserve history and detect concurrent changes. See workspace and Library guide.

In brief: A service-free, skills-led companion for private project memory, bounded context, and semantic Git history. An optional Herdr terminal picker keeps your cards close to the agent draft.

Little Dipper is a small Node 20+ CLI. It keeps semantic memory outside the user's repository and uses only a repository-local Git configuration key for association.

Install

The public beta package is @northstarsoft/little-dipper, version 0.1.0-beta.12. This is an early beta, not a v1 release candidate. After the beta is published to npm, install it with Node.js 20+ and Git available:

npm install -g @northstarsoft/little-dipper
northstar-ld --help

The repository carries its prebuilt dist/ CLI so npm can link northstar-ld immediately, without requiring TypeScript or development dependencies on the user's machine.

The owner's real-task dogfooding so far is with Astra on macOS. Other agents and platforms are beta-test targets, not claimed compatibility results. Start on a noncritical project and back up the private store before testing updates. See beta setup and release notes, including a tarball install route that works before registry publication. In zsh, use rehash if needed.

Let the active agent inspect the bundled skills and deliver them using its current harness knowledge:

northstar-ld skills list
northstar-ld skills path ld
northstar-ld skills export all --to /path/chosen/by/the-agent

path makes no changes. export copies complete skill directories only to the explicit destination and refuses to replace existing content. Little Dipper does not encode harness configuration paths or installation policy in skill delivery. The optional Herdr adapter is delivered separately.

Installing the npm CLI does not install a skill into your harness. Printing skills path only locates it; restarting the harness cannot discover a skill that has not been delivered to a discovery directory. The skills work with any capable harness and need no MCP connection or hooks. To stop automatic guidance, disable or remove a skill's entry through your harness; the CLI and private records remain usable without it.

For local Codex, deliver all seven names returned by skills list: ld, ld-plot-a-course, ld-map-the-project, ld-point-north, ld-tell-me-a-story, ld-work-the-problem, and ld-argh. Link each directory returned by skills path NAME into ~/.agents/skills/NAME (or use skills export all --to ~/.agents/skills). Preserve existing destinations. Codex supports linked skill folders, so a link follows updates to this installation. Verify all seven appear enabled in Codex's skill list before treating setup as complete. New turns should discover it; if the list remains stale, restart. See Codex skill discovery. This is a harness-specific setup example, not CLI installation policy.

For an existing installation, migrate the old bundled discovery entries to the canonical names above; do not leave both copies enabled. Preserve customized copies and archive the former standalone Argh before enabling Work the Problem and the new Argh! voice. CLI skills path/export accepts the five old bundled names as aliases but returns/exports the canonical name, not a duplicate skill. The product stays Little Dipper; $ld is its short skill invocation. The other invocations share $ld-; CLI commands such as northstar-ld orient are unchanged.

Git-install contract

Git installation remains a supported alternative distribution route. Keep the prebuilt dist/ files committed, and do not add npm lifecycle scripts named build, prepare, prepack, preinstall, install, or postinstall to package.json: npm treats any of them as a reason to rebuild a Git dependency during installation. That rebuild runs in a temporary clone and can fail before the global executable is linked. Use npm run compile for local development instead.

If an older global install left a broken link, repair it with:

npm uninstall -g little-dipper
npm install -g @northstarsoft/little-dipper
rehash
northstar-ld --help

The default private store is ~/.northstar/little-dipper. Use --root PATH for an explicit storage root. For another computer, use an private GitHub memory store. init changes no tracked or ordinary working-tree files; it writes only .git/config and the external record. link PROJECT_ID is always explicit and rejects conflicting identity.

To share an existing project, install GitHub CLI (gh) and update Little Dipper to the latest @northstarsoft/little-dipper. On the machine with its records, from the project checkout:

northstar-ld connect YOUR_GITHUB_USER/little-dipper-memory --create
northstar-ld share

On each client (GitHub login opens when needed):

northstar-ld connect YOUR_GITHUB_USER/little-dipper-memory
cd /path/to/checkout
northstar-ld attach
northstar-ld orient

share uploads only this project's durable memory to a dedicated private repository, retaining the original local records. attach selects the sole project or offers a picker; agents can supply its UUID explicitly. The same card, Library and work-session commands sync automatically over HTTPS. No SSH, home server, or always-on Mac. GitHub must be reachable; no offline writes or silent replacement projects. Git facts and work-session cursors stay local.

Shared-cache maintenance is automatic: unchanged reads reuse the current view, and obsolete snapshots are pruned while protecting pending writes and local recovery artifacts. For caches accumulated by older builds, use northstar-ld cache prune --dry-run to preview cleanup, then northstar-ld cache prune. See cache and recovery details.

Start using it on a project

Optional Herdr terminal picker

Use northstar-ld herdr path to locate the bundled plugin, then link that directory with herdr plugin link PATH --enabled. From a linked checkout's pane, run herdr plugin action invoke little-dipper.cards.open. It reads the checkout's linked records live even while the agent is busy. Insertion requires an idle Codex draft and adds selected context without Enter; other panes browse read-only. For standalone read-only browsing, use northstar-ld herdr browse.

Herdr setup, controls, lifecycle and safety include the optional shortcut. No existing Herdr configuration is changed automatically. Import existing records using the Big Dipper import workflow. An unlinked checkout must be explicitly linked before browsing. Native draft insertion for this port still needs owner dogfooding.

Agent workflow

Ask your agent to load the skill returned by northstar-ld skills path ld. No server or connector is needed. Agree on the destination and ask the agent to initialize the private record and author an outcome. Copyable manifests are in the authoring reference.

On a later session, from the project's checkout:

northstar-ld orient
northstar-ld start CARD_ID_OR_CALLSIGN --from session.json

The session input names the actual agent actor; see the copyable examples in the work-session reference. All JSON inputs accept --from - for stdin instead of a file. Read start's brief and requiredReads, then work normally. Orient chooses only a unique in-progress card; otherwise choose an ID explicitly. Unfinished work excludes retired cards. Use orient --include-retired to reveal them; card-show and card-history still work directly. In the TUI and Herdr, click Show retired or press Ctrl-X. Ctrl-D retires a card with a reason and optional replacement callsign; it does not delete history or mark the work complete.

Unfinished work is paginated: orient - 20 gets the second page, or orient CARD_ID 20 keeps an explicit current outcome. Work context retains parent constraints and relevant changes; handoff checks unfinished dependencies and integration scope. Finishing a child does not complete its parent.

Cards can classify linked documents as required context or optional references using sourceRoles; required sources explain why they matter. Existing links stay mandatory for the active card until deliberately classified—no automatic migration. See authoring examples.

Checkpoint consequential progress; handoff can combine progress, actual commit SHAs and test evidence without a duplicate checkpoint. Retain workId/latest seen, and resume with start when switching cards or refreshing changed context—not on every edit. Card creation, status changes and Library writes remain explicit. Human acceptance is separate from implementation and review readiness.

prepare, record and verify remain available for explicit packet requests, legacy flat cards and record reconciliation; they are not a second routine to run alongside work sessions. Read-only questions use orient/card-show without writes. Disable/remove the skill in your harness to stop automatic guidance; CLI and records remain usable. The work-session contract records the pre-promotion rollback point and the limits of current dogfooding evidence.

Install this checkout's prebuilt CLI with npm install -g .. Git/SSH installs receive these changes only after you review and push. If your harness uses copied skills, re-export to a new explicit directory; existing exports are never overwritten. Recompilation is needed only after changing the CLI source.

Command surface

start, checkpoint, handoff, init, apply, link, orient, card-show CARD_ID, card-search QUERY, queue show|history|add CARD|set, prepare CARD_ID, record SHA, verify, reconcile, and map --watch are deterministic local commands. map serves a temporary localhost-only, read-only projection of the Northstar, celestial card timelines, tranche readiness and dependencies, Journey records, prepared packet freshness, and evidence. It reloads when private project records change; it does not provide editing or a hosted service.

Course manifests

Plot a Course can hand Little Dipper a JSON manifest. init --empty creates a blank private record. init --from manifest.json creates and links a new project; apply manifest.json updates an already linked project. An init manifest has schemaVersion: 1, a Markdown northstar, and a non-empty cards array. An apply manifest is partial, requires expectedRevision, and preserves omitted records. Each card has schemaVersion, a safe id, title, purpose, whyNow, string-array constraints and acceptance, and a string revision. Optional decisions, assumptions, evidence, and architecture are validated and written privately. A stale expectedRevision fails; this is not a lock or a multi-writer transaction. Manifest cards are the legacy mutable format. Prefer celestial cards for new work and append events to revise them.

verify CARD_ID --from evidence.json records caller-supplied evidence; it does not execute the command. It stores the command, exit code, summary, source, timestamp, and a bounded output preview. The input shape is { "schemaVersion": 1, "cardId": "…", "command": "…", "exitCode": 0, "summary": "…", "source": "…", "output": "…" }.

Example:

{
  "schemaVersion": 1,
  "northstar": "# Project\\n\\n> **In brief:** A durable destination.\\n",
  "cards": [{
    "schemaVersion": 1,
    "id": "first-leg",
    "title": "First leg",
    "purpose": "Make the first result true.",
    "whyNow": "The project has started.",
    "constraints": ["Private storage"],
    "acceptance": ["A record exists"],
    "revision": "1"
  }]
}

Generic harness seam

Celestial cards and tranches

card-create --from card.json creates an immutable celestial identity and append-only creation event. card-append CARD_ID --from event.json records an attributed observation or state transition without rewriting history.

tranche-create --from tranche.json accepts a validated tree of coherent outcomes. Nodes declare a manifest-local key, working title, purpose, why-now, constraints, acceptance, optional parent, dependsOn, paths, execution tier, and integration responsibility. The result identifies independent ready leaves for a parallel-capable harness; a local agent can work through the same tree sequentially. Little Dipper records the tree but does not launch agents.

card-updated patches the contract: omitted fields keep their values and null removes an optional one; identity and old events are never replaced. acceptance-invalidated projects the card as blocked; an explicit later status event can reopen it. Recent explanations include event-source paths for deeper reading. Concurrent events are preserved and deterministically ordered, not semantically arbitrated. Done is not human acceptance.

Explicit prepare packets are capped at 32,768 UTF-8 bytes (not a tokenizer guarantee). Oversized architecture/Journey/decision enrichment is omitted with source notices. Oversized critical scope fails before replacing the old packet. Recent activity previews are bounded and marked when truncated. An omitted source has not been reviewed.

Freshness hashes HEAD, index, tracked/nonignored-untracked file bytes, authored context, and the card graph. Successive dirty edits invalidate packets. Hashes are stored, not source text or diffs. This conservative v0.1 check can invalidate unrelated work and reads the whole checkout. Large-repository cost and submodule internals need further work. Concurrent edits are not an atomic snapshot; missing or malformed inputs are reported, not treated as fresh.

Harnesses need only invoke the CLI and read its returned brief and required source pages (or an explicitly requested prepare artifact). The package ships seven portable skills:

• ld — resume, execute, verify, record, and hand off work;
• ld-plot-a-course — shape and persist an approved new project;
• ld-map-the-project — reconstruct sourced architecture and Git meaning;
• ld-point-north — give a bounded read-only bearing;
• ld-tell-me-a-story — narrate the sourced course and suggest a next direction;
• ld-work-the-problem — evidence-led engineering and repeated-failure recovery;
• ld-argh — succinct, lightly nautical conversation (Argh!).

An agent can use skills list to discover the suite, skills path NAME when its harness can load a packaged skill directly, or skills export NAME|all --to DIR when the harness needs its own copy. The agent—not Little Dipper—chooses the destination and follows the harness's current installation rules. Do not export skills into the project repository. No MCP server, account, token, or harness-specific bridge is required.

Development

npm install
npm run typecheck
npm test
npm run lint
npm run compile
npm run smoke:package
npm pack --dry-run

Pool evaluation should record the harness/model, packet version, repository commit, commands, timings, acceptance result, and any human intervention. This repository does not claim a Pool result until that external run exists. See Astra-readiness evidence and limits for the current v0.1 handoff. The package smoke uses a temporary install prefix, not your global installation.

License

Copyright (c) 2026 Zachary Braddy. Licensed under the GNU General Public License, version 3 only (GPL-3.0-only); see LICENSE and COPYRIGHT. There is no warranty. The npm artifact includes src/, tsconfig.json and build/test scripts alongside the compiled CLI. To rebuild an extracted package, run npm install --include=dev followed by npm run compile on a POSIX shell.