@edspencer/paddock 0.66.2 → 0.68.0

package/README.md

@@ -75,51 +75,45 @@ mcpServers:
       NOTION_TOKEN: env:NOTION_TOKEN
 ```
 
-## Open your own project
-
-```sh
-cd ~/code/some-project        # somewhere you've used Claude Code
-npx @edspencer/paddock --here
-```
-
-`--here` opens **that directory** as Paddock's workspace: Claude works in your files,
-and any Claude Code sessions you already have for the directory are offered for
-import. It's the fastest way to see what Paddock does with real history instead of an
-empty instance. Later runs in the same directory resume it — no flag needed.
-
-The flag is the consent, so here is everything it does:
-
-- creates **`.paddock/`** for the workspace's state and **`.chats/`** for transcripts
-- appends those two entries to **`.gitignore`**
-
-**Nothing is written into your `~/.claude`** — no file, no symlink. Paddock uses a
-Claude home of its own under `.paddock/` and relocates transcripts into `.chats/`.
-Sessions found in `~/.claude` are *offered* for import: nothing is moved, copied or
-linked until you confirm, and your terminal `claude` keeps working exactly as before.
-To share one set of transcripts between Paddock and your terminal instead, set
+## Open your own projects
+
+A brand-new instance is empty, so it opens on **Discover**. That reads your Claude
+Code history, works out which directories on this machine you have actually been
+using `claude` in, and offers them as projects — with conversation counts, last-used
+dates and git remotes, so you can tell them apart.
+
+Tick the ones you want and press Import. Each becomes a project pointing at that
+directory, with its conversations copied in as chats you can resume — so instead of
+an empty instance you are looking at your own work. Expand a row first if you would
+rather pick individual conversations than take the lot. Discover stays in the sidebar
+afterwards; it is not only a first-run screen.
+
+**Nothing is written into the directories you import.** No `.paddock/`, no `.chats/`,
+no `.gitignore` edit, no `CLAUDE.md`. The project record and the copied transcripts
+both live in the data dir, and the project simply points at the path.
+
+**Your `~/.claude` is not touched either.** Transcripts are *copied*, with their
+timestamps preserved — the originals are never moved or deleted, and your terminal
+`claude` keeps working exactly as before. To share **one** set of transcripts between
+Paddock and your terminal rather than keeping a copy, set
 `claude: { transcripts: host }` in `<data-dir>/paddock.config.yaml`. (Your *login* is
 already shared, which is why there is nothing to log into — see Credentials above.)
 
-To undo it: `rm -rf .paddock .chats` and drop the two `.gitignore` lines.
-
-Without `--here`, Paddock never touches the directory you ran it from.
-
 ## Options
 
 ```
   -p, --port <port>       HTTP/WS port (default 7233)
       --host <host>       Bind address (default 127.0.0.1)
   -d, --data-dir <path>   Projects + state (default ~/.paddock)
-      --here              Open the CURRENT directory as the workspace
   -o, --open              Open the app in your browser once it is listening
       --verbose           Show the server's own logs (quiet by default)
   -v, --version           Print the version
   -h, --help              Show help
 ```
 
-Your projects, chats and settings persist between runs in `~/.paddock` — or in
-`<dir>/.paddock` when you use `--here`. Either way it's one directory: move it to
-move your instance, delete it to start over.
+Your projects, chats and settings persist between runs in `~/.paddock`, or wherever
+`--data-dir` points. It is one directory: move it to move your instance, delete it to
+start over. Where you run `paddock` from has no effect on which instance you get.
 
 ## Security
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edspencer/paddock",
-  "version": "0.66.2",
+  "version": "0.68.0",
   "description": "Project-first launchpad for Claude Code: server-hosted, persistent, resumable sessions organized by project.",
   "keywords": [
     "claude",

package/packages/server/dist/adoptable.d.ts

@@ -104,6 +104,14 @@ export declare const SLASH_COMMAND_MAX_BYTES = 4096;
  * it pasted into a test here would go stale silently and take the filter with it.
  */
 export declare function isSweeperPrompt(preview: string): boolean;
+/**
+ * Classify a candidate as noise, or `null` to keep it.
+ *
+ * Exported for `discover.ts` (#745), which counts a directory's NON-NOISE
+ * sessions to rank it. The count a Discover row shows and the offer the import
+ * dialog then makes have to be the same number, so both go through this.
+ */
+export declare function filterReasonFor(session: AdoptableSession): FilterReason | null;
 /**
  * Reduce a git remote URL to a comparable `host/path` identity (#659).
  *
@@ -145,6 +153,31 @@ export declare function gitRemotes(cwd: string): Promise<string[]>;
 export interface AdoptableFleet {
     listAdoptableSessions(agentName: string, fromWorkingDir?: string): Promise<AdoptableSession[]>;
 }
+/**
+ * One `<claudeHome>/projects/*` folder, with its recorded cwd recovered.
+ *
+ * Exported for `discover.ts` (#745): instance-level discovery asks the SAME
+ * question this module's cache already answers — "which directories on this
+ * machine have transcript folders, and what cwd does each really record" — and
+ * re-scanning would both duplicate the folder→cwd read and miss the legacy
+ * mirroring {@link AdoptableIndex.scanFolders} performs on the way past.
+ */
+export interface TranscriptFolder {
+    /** Folder name under `<claudeHome>/projects/`. */
+    name: string;
+    /** Absolute path, symlinks resolved — the de-dup identity for a source. */
+    realPath: string;
+    /** `mtimeMs:size` of the folder, i.e. "has its file SET changed". */
+    key: string;
+    /** The cwd recorded inside one of its transcripts, or `null` if unknowable. */
+    cwd: string | null;
+    /**
+     * The path to hand the engine to read THIS folder. Equal to {@link cwd} for an
+     * ordinary folder (whose name IS the encoded cwd); the synthetic mirror path
+     * for one of the user's own folders (#620).
+     */
+    engineCwd: string | null;
+}
 /**
  * Per-instance adoptable-session detector with an mtime-keyed cache.
  *
@@ -216,6 +249,18 @@ export declare class AdoptableIndex {
      * string and tests `undefined` explicitly, never truthiness.
      */
     invalidate(projectKey?: string): void;
+    /**
+     * Every transcript folder this instance can see, with its recorded cwd — the
+     * raw material instance-level Discovery (#745) filters into candidate project
+     * directories.
+     *
+     * Deliberately the same call `adoptableFor` makes, cache and legacy mirroring
+     * included, rather than a second scan: the mirroring is what puts the user's
+     * OWN `~/.claude` history in view (#620), and Discovery finding nothing on a
+     * laptop because it skipped that step would be the whole feature failing
+     * silently.
+     */
+    transcriptFolders(): Promise<TranscriptFolder[]>;
     /**
      * Enumerate `<claudeHome>/projects/*`, refreshing the recorded cwd only for
      * folders whose file set changed since last time.
@@ -246,3 +291,15 @@ export declare class AdoptableIndex {
      */
     adoptableFor(fleet: AdoptableFleet, project: Project, agentName: string): Promise<AdoptableSummary>;
 }
+/**
+ * The cwd recorded inside a transcript folder, by reading the head of its
+ * newest-looking `.jsonl`.
+ *
+ * Every session in a folder shares the encoded cwd, so ONE read identifies the
+ * folder. Files are tried in readdir order until one yields a cwd, because a
+ * zero-byte or truncated transcript records none (the QA corpus has both).
+ *
+ * Exported so nothing else is ever tempted to invert `encodePathForCli` — the
+ * encoding is lossy and the folder name is NOT a cwd (see this module's header).
+ */
+export declare function recordedCwd(dir: string): Promise<string | null>;

package/packages/server/dist/adoptable.js

@@ -154,8 +154,14 @@ const SWEEPER_PROMPT_RE = /^Project: .*\(slug: [^)]*\)\s+(?:Summary:.*\s+)?You a
 export function isSweeperPrompt(preview) {
     return SWEEPER_PROMPT_RE.test(preview);
 }
-/** Classify a candidate as noise, or `null` to keep it. */
-function filterReasonFor(session) {
+/**
+ * Classify a candidate as noise, or `null` to keep it.
+ *
+ * Exported for `discover.ts` (#745), which counts a directory's NON-NOISE
+ * sessions to rank it. The count a Discover row shows and the offer the import
+ * dialog then makes have to be the same number, so both go through this.
+ */
+export function filterReasonFor(session) {
     if (session.sizeBytes < MIN_TRANSCRIPT_BYTES)
         return "too-small";
     if (session.preview !== undefined && isSweeperPrompt(session.preview)) {
@@ -333,6 +339,20 @@ export class AdoptableIndex {
         else
             this.summaries.delete(projectKey);
     }
+    /**
+     * Every transcript folder this instance can see, with its recorded cwd — the
+     * raw material instance-level Discovery (#745) filters into candidate project
+     * directories.
+     *
+     * Deliberately the same call `adoptableFor` makes, cache and legacy mirroring
+     * included, rather than a second scan: the mirroring is what puts the user's
+     * OWN `~/.claude` history in view (#620), and Discovery finding nothing on a
+     * laptop because it skipped that step would be the whole feature failing
+     * silently.
+     */
+    async transcriptFolders() {
+        return this.scanFolders();
+    }
     /**
      * Enumerate `<claudeHome>/projects/*`, refreshing the recorded cwd only for
      * folders whose file set changed since last time.
@@ -547,8 +567,11 @@ export class AdoptableIndex {
  * Every session in a folder shares the encoded cwd, so ONE read identifies the
  * folder. Files are tried in readdir order until one yields a cwd, because a
  * zero-byte or truncated transcript records none (the QA corpus has both).
+ *
+ * Exported so nothing else is ever tempted to invert `encodePathForCli` — the
+ * encoding is lossy and the folder name is NOT a cwd (see this module's header).
  */
-async function recordedCwd(dir) {
+export async function recordedCwd(dir) {
     const entries = await fs.readdir(dir).catch(() => []);
     for (const entry of entries) {
         if (!entry.endsWith(".jsonl"))

package/packages/server/dist/agent-errors.js

@@ -1,7 +1,7 @@
 /**
  * Making a failed agent run readable (#684).
  *
- * A credential-less `npx @edspencer/paddock --here` — the path the README, the
+ * A credential-less `npx @edspencer/paddock` — the path the README, the
  * docs site and the front page all point new users at — greeted them with a
  * multi-screen stack trace containing the entire sweeper system prompt, four
  * times over: once in the `ExecaError`, once in the `[fleet-manager]` line, once

package/packages/server/dist/claude-home.d.ts

@@ -244,10 +244,10 @@ export interface PlantedChatsLink {
  * by {@link countLegacyTranscriptLinks} as harmless pre-#620 residue, and they
  * are: they were planted for a project whose transcripts paddock does own.
  *
- * The ones this finds are the poisoned kind. Under `--here` the workspace's
- * `.chats/` sits at `<dir>/.chats` while the data dir is `<dir>/.paddock`, so a
- * link planted by an affected build points somewhere no `dataDir` prefix match
- * will ever catch. While it exists, every `claude` session the user starts in
+ * The ones this finds are the poisoned kind. Under `--here` — removed in #798,
+ * but the residue outlives it — the workspace's `.chats/` sat at `<dir>/.chats`
+ * while the data dir was `<dir>/.paddock`, so a link planted by an affected build
+ * points somewhere no `dataDir` prefix match will ever catch. While it exists, every `claude` session the user starts in
  * that directory writes into paddock's store instead of their own history, and
  * anything that expects `~/.claude/projects/<enc>` to be a real directory
  * (`unzip -d ~/.claude` being the observed one) fails with an error impossible

package/packages/server/dist/claude-home.js

@@ -695,10 +695,10 @@ export async function countLegacyTranscriptLinks(legacyHome, dataDir) {
  * by {@link countLegacyTranscriptLinks} as harmless pre-#620 residue, and they
  * are: they were planted for a project whose transcripts paddock does own.
  *
- * The ones this finds are the poisoned kind. Under `--here` the workspace's
- * `.chats/` sits at `<dir>/.chats` while the data dir is `<dir>/.paddock`, so a
- * link planted by an affected build points somewhere no `dataDir` prefix match
- * will ever catch. While it exists, every `claude` session the user starts in
+ * The ones this finds are the poisoned kind. Under `--here` — removed in #798,
+ * but the residue outlives it — the workspace's `.chats/` sat at `<dir>/.chats`
+ * while the data dir was `<dir>/.paddock`, so a link planted by an affected build
+ * points somewhere no `dataDir` prefix match will ever catch. While it exists, every `claude` session the user starts in
  * that directory writes into paddock's store instead of their own history, and
  * anything that expects `~/.claude/projects/<enc>` to be a real directory
  * (`unzip -d ~/.claude` being the observed one) fails with an error impossible

package/packages/server/dist/claude-mcp.d.ts

@@ -70,8 +70,10 @@ export interface HostMcpCaveat {
  * top-level `mcpServers` that applies everywhere, and a
  * `projects[<absolute dir>].mcpServers` that applies only in that directory. The
  * per-directory one is keyed by the LITERAL absolute path — not the `-`-encoded
- * form the transcript folders use — and it is the scope a `--here` workspace
- * hits, because `claude mcp add` without `--scope user` writes there.
+ * form the transcript folders use — and it is the scope a project linked at
+ * that path hits, because `claude mcp add` without `--scope user` writes there.
+ * (It used to say "a `--here` workspace"; that flag is gone as of #798, but the
+ * point survives it — a `path:` project reaches exactly the same entry.)
  *
  * {@link declared} is the third contributor and the one that is not the host's at
  * all: paddock's own top-level `mcpServers:` config block (#691 step 6), resolved

package/packages/server/dist/cli/args.d.ts

@@ -27,7 +27,6 @@ export interface CliOptions {
     port?: string;
     host?: string;
     dataDir?: string;
-    here: boolean;
     open: boolean;
     verbose: boolean;
     help: boolean;
@@ -37,6 +36,45 @@ export interface CliOptions {
 export declare class CliError extends Error {
 }
 export declare const MIN_NODE_MAJOR = 22;
+/** What `paddock service` can be asked to do. */
+export declare const SERVICE_ACTIONS: readonly ["install", "uninstall", "status"];
+export type ServiceAction = (typeof SERVICE_ACTIONS)[number];
+/** The leading words {@link parseCommand} recognises. Anything else is a flag. */
+export declare const VERBS: readonly ["start", "service"];
+/**
+ * A parsed invocation: which verb, plus the flags that followed it.
+ *
+ * `action` is optional on `service` for exactly one reason — `paddock service
+ * --help`, where there is no action to name and printing usage is the whole
+ * request. It is `undefined` only when `opts.help` is true.
+ */
+export type Command = {
+    verb: "start";
+    opts: CliOptions;
+} | {
+    verb: "service";
+    action: ServiceAction | undefined;
+    opts: CliOptions;
+};
+/**
+ * Split a leading verb off the argv, then parse the rest as flags.
+ *
+ * The dispatch is deliberately a check on `argv[0]` alone rather than a scan for
+ * the first non-flag token, and it happens BEFORE the flag loop. Two properties
+ * fall out of that, both of which matter more than the flexibility given up:
+ *
+ * - **Bare `paddock` is untouched.** No verb means the whole argv goes to
+ *   {@link parseArgs} exactly as before, so the demo path cannot change
+ *   behaviour, and an unrecognised leading token still produces `unknown
+ *   option:` from the flag loop rather than a new and different error.
+ * - **Flags parse after a verb**, so `paddock start --port 7299` and
+ *   `paddock service install --port 7299` both work, and the flag grammar is
+ *   the same one in every position.
+ *
+ * A verb is only a verb in first position: `paddock --port start` is still a
+ * missing-value error, and `paddock start start` is still `unknown option`.
+ */
+export declare function parseCommand(argv: string[]): Command;
 export declare function parseArgs(argv: string[]): CliOptions;
 /**
  * Why this Node is unusable, or `undefined` if it is fine.
@@ -53,4 +91,5 @@ export declare function nodeVersionProblem(nodeVersion: string): string | undefi
  * names neither the port nor the flag that fixes it.
  */
 export declare function explainListenError(err: unknown, host: string, port: string): string;
-export declare const USAGE = "paddock \u2014 run a Paddock instance locally\n\nUsage\n  npx @edspencer/paddock [options]\n\nOptions\n  -p, --port <port>       HTTP/WS port (default 7233, or $PORT)\n      --host <host>       Bind address (default 127.0.0.1)\n  -d, --data-dir <path>   Projects + state (default ~/.paddock, or $PADDOCK_DATA_DIR)\n      --here              Open the CURRENT directory as the workspace (see below)\n  -o, --open              Open the app in your browser once it is listening\n      --verbose           Show the server's own logs (quiet by default)\n  -v, --version           Print the Paddock version and exit\n  -h, --help              Show this help\n\nOpening a directory (--here)\n  Run `paddock --here` inside a project and Paddock opens THAT directory as its\n  workspace: Claude works in your files, and any Claude Code sessions you already\n  have for the directory are offered for import. It:\n\n    \u00B7 creates .paddock/ in the directory for this workspace's own state\n    \u00B7 creates .chats/ for transcripts, and adds both to .gitignore\n    \u00B7 offers your ~/.claude sessions for this directory for import \u2014 nothing\n      there is moved, copied or linked until you confirm\n\n  Once done, later runs in the same directory resume it \u2014 no flag needed.\n  Without --here, Paddock never touches the directory you ran it from.\n\nCredentials\n  Paddock drives Claude Code, so it needs Claude credentials \u2014 and if you\n  already use Claude Code on this machine, it uses the login you already have.\n  That is a macOS Keychain entry on a Mac, or your ~/.claude/.credentials.json\n  elsewhere (symlinked in, never copied). Reading a login writes nothing.\n\n  Otherwise: a CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY in the environment,\n  or a one-off `CLAUDE_CONFIG_DIR=<data-dir>/claude-home claude login`. With no\n  login at all anywhere, run `claude setup-token`. Paddock says at startup when\n  it can find none.\n\nSharing your Claude Code state\n  Apart from that login, Paddock writes nothing outside its data dir by\n  default: transcripts go to each project's .chats/, and your ~/.claude is read\n  for config only. Each thing it can share is one key in\n  <data-dir>/paddock.config.yaml:\n\n    claude:\n      transcripts: host   # own | host, default own\n      credentials: host   # own | host, default host\n      instructions: host  # own | host, default own\n      hooks: host         # own | host, default own\n      mcpServers: host    # own | host, default own\n\n  transcripts: host makes a chat and a `claude --resume` in the same directory\n  the same file, live in both directions; deleting such a chat in Paddock\n  releases it rather than removing it, because it is your history rather than\n  Paddock's copy. credentials: own is the opt-out from sharing the login above.\n\n  instructions: host loads your ~/.claude CLAUDE.md, agents/, commands/ and\n  plugins/. Off by default, which is a change: your curated CLAUDE.md does not\n  reach Paddock's agents unless you say so. Each project's own CLAUDE.md always\n  does.\n\n  hooks: host runs the shell commands your ~/.claude/settings.json binds to\n  tool use. Off by default \u2014 inheriting someone's hooks is not something to\n  discover after the fact. Its other keys (permissions, model, statusline)\n  apply either way: under hooks: own Paddock writes its own settings.json\n  carrying them with hooks dropped, regenerated at startup.\n\n  mcpServers: host attaches the MCP servers declared in your ~/.claude.json \u2014\n  the top-level ones, plus a project's own when its directory matches. To give\n  this instance a server your machine doesn't have, declare it instead in a\n  sibling mcpServers: block of the same file; use env:VAR_NAME anywhere a\n  string goes so tokens stay out of it. That keeps a token out of the file, not\n  out of `ps`: leave driveMode on its default (session) for a server holding\n  one, since batch passes the definition to claude as a command-line argument.\n\nYour data\n  Everything lives in one directory \u2014 ~/.paddock unless you pass --data-dir.\n  Projects, chat transcripts and settings all persist there between runs. Move\n  that directory to move your instance; delete it to start over. Nothing is\n  stored anywhere else.\n\nNotes\n  Binds loopback with authentication disabled, which is safe for a laptop. To\n  expose it on a network, set PADDOCK_AUTH_MODE first \u2014 Paddock refuses to bind\n  a routable interface wide open. See AUTH.md.\n\nDocs: https://github.com/edspencer/paddock";
+export declare const USAGE = "paddock \u2014 run a Paddock instance locally\n\nUsage\n  npx @edspencer/paddock [options]        start the server (the default)\n  paddock start [options]                 the same thing, said out loud\n  paddock service <install|uninstall|status>\n                                          run it in the background from login\n                                          (`paddock service --help`)\n\nOptions\n  -p, --port <port>       HTTP/WS port (default 7233, or $PORT)\n      --host <host>       Bind address (default 127.0.0.1)\n  -d, --data-dir <path>   Projects + state (default ~/.paddock, or $PADDOCK_DATA_DIR)\n  -o, --open              Open the app in your browser once it is listening\n      --verbose           Show the server's own logs (quiet by default)\n  -v, --version           Print the Paddock version and exit\n  -h, --help              Show this help\n\nOpening your own directories\n  Where you run this from does not matter \u2014 the instance is decided by its data\n  dir alone. Directories are added inside the app, on the Discover screen: it\n  reads your Claude Code history, lists the directories you have worked in, and\n  links the ones you tick as projects. A new instance opens on it.\n\n  Importing a directory does not write into it. No .paddock/, no .chats/, no\n  .gitignore edits, no CLAUDE.md \u2014 the project record and the copied transcripts\n  both live in the data dir, and the project just points at the path. Your own\n  ~/.claude transcripts are copied, never moved or deleted, so your terminal\n  `claude` keeps working exactly as before.\n\nCredentials\n  Paddock drives Claude Code, so it needs Claude credentials \u2014 and if you\n  already use Claude Code on this machine, it uses the login you already have.\n  That is a macOS Keychain entry on a Mac, or your ~/.claude/.credentials.json\n  elsewhere (symlinked in, never copied). Reading a login writes nothing.\n\n  Otherwise: a CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY in the environment,\n  or a one-off `CLAUDE_CONFIG_DIR=<data-dir>/claude-home claude login`. With no\n  login at all anywhere, run `claude setup-token`. Paddock says at startup when\n  it can find none.\n\nSharing your Claude Code state\n  Apart from that login, Paddock writes nothing outside its data dir by\n  default: transcripts go to each project's .chats/, and your ~/.claude is read\n  for config only. Each thing it can share is one key in\n  <data-dir>/paddock.config.yaml:\n\n    claude:\n      transcripts: host   # own | host, default own\n      credentials: host   # own | host, default host\n      instructions: host  # own | host, default own\n      hooks: host         # own | host, default own\n      mcpServers: host    # own | host, default own\n\n  transcripts: host makes a chat and a `claude --resume` in the same directory\n  the same file, live in both directions; deleting such a chat in Paddock\n  releases it rather than removing it, because it is your history rather than\n  Paddock's copy. credentials: own is the opt-out from sharing the login above.\n\n  instructions: host loads your ~/.claude CLAUDE.md, agents/, commands/ and\n  plugins/. Off by default, which is a change: your curated CLAUDE.md does not\n  reach Paddock's agents unless you say so. Each project's own CLAUDE.md always\n  does.\n\n  hooks: host runs the shell commands your ~/.claude/settings.json binds to\n  tool use. Off by default \u2014 inheriting someone's hooks is not something to\n  discover after the fact. Its other keys (permissions, model, statusline)\n  apply either way: under hooks: own Paddock writes its own settings.json\n  carrying them with hooks dropped, regenerated at startup.\n\n  mcpServers: host attaches the MCP servers declared in your ~/.claude.json \u2014\n  the top-level ones, plus a project's own when its directory matches. To give\n  this instance a server your machine doesn't have, declare it instead in a\n  sibling mcpServers: block of the same file; use env:VAR_NAME anywhere a\n  string goes so tokens stay out of it. That keeps a token out of the file, not\n  out of `ps`: leave driveMode on its default (session) for a server holding\n  one, since batch passes the definition to claude as a command-line argument.\n\nYour data\n  Everything lives in one directory \u2014 ~/.paddock unless you pass --data-dir.\n  Projects, chat transcripts and settings all persist there between runs. Move\n  that directory to move your instance; delete it to start over. Nothing is\n  stored anywhere else.\n\nNotes\n  Binds loopback with authentication disabled, which is safe for a laptop. To\n  expose it on a network, set PADDOCK_AUTH_MODE first \u2014 Paddock refuses to bind\n  a routable interface wide open. See AUTH.md.\n\nDocs: https://github.com/edspencer/paddock";
+export declare const SERVICE_USAGE = "paddock service \u2014 keep Paddock running in the background\n\nUsage\n  paddock service install [options]   register it and start it now\n  paddock service uninstall           stop it and deregister it\n  paddock service status              is it registered, is it running, where are the logs\n\nOptions (install only \u2014 recorded in the generated unit)\n  -p, --port <port>       HTTP/WS port (default 7233)\n      --host <host>       Bind address (default 127.0.0.1)\n  -d, --data-dir <path>   Only if you want an instance SEPARATE from your\n                          terminal one. Omitted by default on purpose, so\n                          `paddock service` and a bare `paddock` are the same\n                          ~/.paddock instance reached two ways.\n      --verbose           Record the server's own logs, not just warnings\n\nAt login, not at boot\n  This registers a per-USER service \u2014 a launchd LaunchAgent on macOS, a\n  `systemd --user` unit on Linux \u2014 so it runs as you, with your own Claude\n  login. That is not incidental: on macOS your Claude login is a Keychain item\n  that only a logged-in user session can read. A boot-time system daemon has no\n  such session and could not use it.\n\n  So Paddock starts when you LOG IN, not when the machine boots. After a\n  restart that nobody logs into, Paddock is not running. That is the design, not\n  a fault.\n\n  On Linux, a user service is also stopped when you log out. To keep it up:\n\n    loginctl enable-linger $USER\n\nWhere it lives\n  macOS   ~/Library/LaunchAgents/net.edspencer.paddock.plist\n          logs in <data-dir>/service/\n  Linux   ~/.config/systemd/user/paddock.service\n          logs via  journalctl --user -u paddock -f\n\nInstalled from npx?\n  `service install` refuses. An npx cache path is hash-keyed and npm may prune\n  it, so the unit would work until it silently didn't, at some future login.\n  Install properly first:\n\n    npm i -g @edspencer/paddock && paddock service install\n\nA note on access\n  Paddock binds loopback with authentication off, which is right for a laptop.\n  A service is up for as long as you are logged in rather than as long as a\n  terminal tab, so that window is longer \u2014 but it is not wider: any local\n  process that could reach the port could already read the same Claude login as\n  you. Set PADDOCK_AUTH_MODE if you want a credential on it anyway.\n\nDocs: https://github.com/edspencer/paddock";

package/packages/server/dist/cli/args.js

@@ -27,9 +27,60 @@
 export class CliError extends Error {
 }
 export const MIN_NODE_MAJOR = 22;
+/** What `paddock service` can be asked to do. */
+export const SERVICE_ACTIONS = ["install", "uninstall", "status"];
+/** The leading words {@link parseCommand} recognises. Anything else is a flag. */
+export const VERBS = ["start", "service"];
+function isServiceAction(token) {
+    return SERVICE_ACTIONS.includes(token);
+}
+/**
+ * Split a leading verb off the argv, then parse the rest as flags.
+ *
+ * The dispatch is deliberately a check on `argv[0]` alone rather than a scan for
+ * the first non-flag token, and it happens BEFORE the flag loop. Two properties
+ * fall out of that, both of which matter more than the flexibility given up:
+ *
+ * - **Bare `paddock` is untouched.** No verb means the whole argv goes to
+ *   {@link parseArgs} exactly as before, so the demo path cannot change
+ *   behaviour, and an unrecognised leading token still produces `unknown
+ *   option:` from the flag loop rather than a new and different error.
+ * - **Flags parse after a verb**, so `paddock start --port 7299` and
+ *   `paddock service install --port 7299` both work, and the flag grammar is
+ *   the same one in every position.
+ *
+ * A verb is only a verb in first position: `paddock --port start` is still a
+ * missing-value error, and `paddock start start` is still `unknown option`.
+ */
+export function parseCommand(argv) {
+    const [first, ...rest] = argv;
+    if (first === "service") {
+        const head = rest[0];
+        let action;
+        if (head !== undefined && !head.startsWith("-")) {
+            // Catch a misspelled action here rather than letting the flag loop call
+            // it an "unknown option", which sends the reader looking for a flag.
+            if (!isServiceAction(head)) {
+                throw new CliError(`unknown service action: ${head}\n` +
+                    `Expected one of: ${SERVICE_ACTIONS.join(", ")}.\n` +
+                    "Run `paddock service --help` for usage.");
+            }
+            action = head;
+        }
+        const opts = parseArgs(action === undefined ? rest : rest.slice(1));
+        // `--help` wins over a missing action: asking for usage is not a usage error.
+        if (action === undefined && !opts.help) {
+            throw new CliError(`\`paddock service\` needs an action: ${SERVICE_ACTIONS.join(", ")}.\n` +
+                "Run `paddock service --help` for usage.");
+        }
+        return { verb: "service", action, opts };
+    }
+    if (first === "start")
+        return { verb: "start", opts: parseArgs(rest) };
+    return { verb: "start", opts: parseArgs(argv) };
+}
 export function parseArgs(argv) {
     const opts = {
-        here: false,
         open: false,
         verbose: false,
         help: false,
@@ -55,9 +106,6 @@ export function parseArgs(argv) {
             case "--data-dir":
                 opts.dataDir = next();
                 break;
-            case "--here":
-                opts.here = true;
-                break;
             case "-o":
             case "--open":
                 opts.open = true;
@@ -115,30 +163,32 @@ export function explainListenError(err, host, port) {
 export const USAGE = `paddock — run a Paddock instance locally
 
 Usage
-  npx @edspencer/paddock [options]
+  npx @edspencer/paddock [options]        start the server (the default)
+  paddock start [options]                 the same thing, said out loud
+  paddock service <install|uninstall|status>
+                                          run it in the background from login
+                                          (\`paddock service --help\`)
 
 Options
   -p, --port <port>       HTTP/WS port (default 7233, or $PORT)
       --host <host>       Bind address (default 127.0.0.1)
   -d, --data-dir <path>   Projects + state (default ~/.paddock, or $PADDOCK_DATA_DIR)
-      --here              Open the CURRENT directory as the workspace (see below)
   -o, --open              Open the app in your browser once it is listening
       --verbose           Show the server's own logs (quiet by default)
   -v, --version           Print the Paddock version and exit
   -h, --help              Show this help
 
-Opening a directory (--here)
-  Run \`paddock --here\` inside a project and Paddock opens THAT directory as its
-  workspace: Claude works in your files, and any Claude Code sessions you already
-  have for the directory are offered for import. It:
-
-    · creates .paddock/ in the directory for this workspace's own state
-    · creates .chats/ for transcripts, and adds both to .gitignore
-    · offers your ~/.claude sessions for this directory for import — nothing
-      there is moved, copied or linked until you confirm
+Opening your own directories
+  Where you run this from does not matter — the instance is decided by its data
+  dir alone. Directories are added inside the app, on the Discover screen: it
+  reads your Claude Code history, lists the directories you have worked in, and
+  links the ones you tick as projects. A new instance opens on it.
 
-  Once done, later runs in the same directory resume it — no flag needed.
-  Without --here, Paddock never touches the directory you ran it from.
+  Importing a directory does not write into it. No .paddock/, no .chats/, no
+  .gitignore edits, no CLAUDE.md — the project record and the copied transcripts
+  both live in the data dir, and the project just points at the path. Your own
+  ~/.claude transcripts are copied, never moved or deleted, so your terminal
+  \`claude\` keeps working exactly as before.
 
 Credentials
   Paddock drives Claude Code, so it needs Claude credentials — and if you
@@ -200,3 +250,55 @@ Notes
   a routable interface wide open. See AUTH.md.
 
 Docs: https://github.com/edspencer/paddock`;
+export const SERVICE_USAGE = `paddock service — keep Paddock running in the background
+
+Usage
+  paddock service install [options]   register it and start it now
+  paddock service uninstall           stop it and deregister it
+  paddock service status              is it registered, is it running, where are the logs
+
+Options (install only — recorded in the generated unit)
+  -p, --port <port>       HTTP/WS port (default 7233)
+      --host <host>       Bind address (default 127.0.0.1)
+  -d, --data-dir <path>   Only if you want an instance SEPARATE from your
+                          terminal one. Omitted by default on purpose, so
+                          \`paddock service\` and a bare \`paddock\` are the same
+                          ~/.paddock instance reached two ways.
+      --verbose           Record the server's own logs, not just warnings
+
+At login, not at boot
+  This registers a per-USER service — a launchd LaunchAgent on macOS, a
+  \`systemd --user\` unit on Linux — so it runs as you, with your own Claude
+  login. That is not incidental: on macOS your Claude login is a Keychain item
+  that only a logged-in user session can read. A boot-time system daemon has no
+  such session and could not use it.
+
+  So Paddock starts when you LOG IN, not when the machine boots. After a
+  restart that nobody logs into, Paddock is not running. That is the design, not
+  a fault.
+
+  On Linux, a user service is also stopped when you log out. To keep it up:
+
+    loginctl enable-linger $USER
+
+Where it lives
+  macOS   ~/Library/LaunchAgents/net.edspencer.paddock.plist
+          logs in <data-dir>/service/
+  Linux   ~/.config/systemd/user/paddock.service
+          logs via  journalctl --user -u paddock -f
+
+Installed from npx?
+  \`service install\` refuses. An npx cache path is hash-keyed and npm may prune
+  it, so the unit would work until it silently didn't, at some future login.
+  Install properly first:
+
+    npm i -g @edspencer/paddock && paddock service install
+
+A note on access
+  Paddock binds loopback with authentication off, which is right for a laptop.
+  A service is up for as long as you are logged in rather than as long as a
+  terminal tab, so that window is longer — but it is not wider: any local
+  process that could reach the port could already read the same Claude login as
+  you. Set PADDOCK_AUTH_MODE if you want a credential on it anyway.
+
+Docs: https://github.com/edspencer/paddock`;