agent-session

Workflow touchpoint launcher — rehydrate sessions and spawn fresh agent CLI sessions with lean context.

Usage (via npx — no install needed)

npx -y agent-session --help
npx -y agent-session prepare --step 2 --branch feature/45-foo --type collab
npx -y agent-session start 'github:mararn1618/memoria-letzte-worte@feature/45-foo:.agent/sessions/collab-2-45-foo/session.yml'
npx -y agent-session approve 'github:mararn1618/memoria-letzte-worte@feature/45-foo:.agent/sessions/collab-2-45-foo/session.yml'

Published on npm as agent-session. npx -y downloads and runs it on the fly without prompting to install the package.

Local development

cd agent/session
npm install
npm link          # makes `agent-session` available globally

After linking, agent-session is on your PATH from any directory. To remove it later: npm unlink -g agent-session.

Commands

prepare

Write a session file for a workflow touchpoint, commit and push it on the current branch.

npx -y agent-session prepare \
  --step 2 \
  --branch improve-agent-harness \
  --type collab \
  --context docs/discussions/2026-04-26_14-36_agent_session_launcher.md \
  --link plan=https://github.com/mararn1618/memoria-letzte-worte/blob/improve-agent-harness/docs/plans/2026-04-26_14-38_agent_session_launcher.md

Options:

| Flag | Required | Description | |------|----------|-------------| | --step <N> | yes | Workflow step number (e.g. 2 for 02_COLLAB_discussion.md) | | --branch <branch> | yes | Git branch the session is anchored to | | --type <collab\|gate> | yes | Touchpoint type — collab for interactive sessions, gate for human-only approvals | | --prompt <path> | no | Override prompt template path (defaults to agent/workflow/<step>_<type>_*.md) | | --context <files...> | no | Repo-relative paths to include as lean context | | --output-folder <path> | no | Where the session writes outputs (defaults to .agent/sessions/<id>/output) | | --link <label=url...> | no | Reference links surfaced in the notification | | --yes | no | Skip the commit/push confirmation prompt |

The command prints a notification block (with the session ref) to stdout — copy it into Telegram/Discord/Slack manually.

start

Rehydrate a prepared session and spawn an interactive Claude Code session in the matching workspace.

npx -y agent-session start 'github:mararn1618/memoria-letzte-worte@improve-agent-harness:.agent/sessions/collab-2-improve-agent-harness/session.yml'

Options:

| Flag | Description | |------|-------------| | --adapter <name> | Agent CLI adapter — only claude is implemented (default) |

The command clones/updates the workspace, assembles the prompt + context files, and execs claude with the resulting prompt. When the agent CLI exits, you get instructions for the next step (approve).

approve

Mark a session completed, advance .active-workflow.yaml (if present), commit and push.

npx -y agent-session approve 'github:mararn1618/memoria-letzte-worte@improve-agent-harness:.agent/sessions/collab-2-improve-agent-harness/session.yml'

Options:

| Flag | Description | |------|-------------| | --yes | Skip the commit/push confirmation prompt |

Session Ref Syntax

Two equivalent forms are accepted everywhere a <session-ref> is expected:

Compact form

github:<owner>/<repo>@<branch>:<path-to-session.yml>

Example:

github:mararn1618/memoria-letzte-worte@improve-agent-harness:.agent/sessions/collab-2-improve-agent-harness/session.yml

GitHub blob URL

https://github.com/<owner>/<repo>/blob/<branch>/<path-to-session.yml>

Example:

https://github.com/mararn1618/memoria-letzte-worte/blob/improve-agent-harness/.agent/sessions/collab-2-improve-agent-harness/session.yml

session.yml Schema

Sessions are written to .agent/sessions/<session-id>/session.yml and committed on the branch that owns the touchpoint.

id: collab-2-improve-agent-harness        # <type>-<step>-<short-branch>
type: collab                              # collab | gate
step: 2                                   # workflow step number
status: waiting_for_human                 # waiting_for_human | completed
git:
  repo: mararn1618/memoria-letzte-worte   # owner/repo
  branch: improve-agent-harness
context:                                  # repo-relative paths assembled into the prompt
  - docs/discussions/2026-04-26_14-36_agent_session_launcher.md
prompt: agent/workflow/02_COLLAB_discussion.md
output_folder: .agent/sessions/collab-2-improve-agent-harness/output
links:                                    # optional
  - label: plan
    url: https://github.com/mararn1618/memoria-letzte-worte/blob/improve-agent-harness/docs/plans/2026-04-26_14-38_agent_session_launcher.md
completed_at: '2026-04-26T15:42:18.314Z'  # set by `approve`

Limitations

• Claude Code only — adapter layer is pluggable, but no other agent CLI (Codex, Gemini, etc.) is implemented.
• Local execution only — start runs the agent CLI on your machine; no remote runner integration.
• Notification messages printed to stdout — no Telegram/Discord/Slack delivery, copy-paste required.
• No GitHub Actions resume trigger — workflow advancement happens only when you run approve locally.

Development

npm run dev -- --help    # run CLI from source via tsx
npm run build            # compile TypeScript to dist/
npm test                 # run vitest once

See test/smoke.md for the manual end-to-end checklist.

References

• Plan: docs/plans/2026-04-26_14-38_agent_session_launcher.md
• Discussion: docs/discussions/2026-04-26_14-36_agent_session_launcher.md