session-forge

Session Forge (sf)

Session Forge orchestrates LLM-assisted development sessions across fleets of machines. It combines SSH automation, git worktrees, and project metadata into a single CLI (sf) that prepares workspaces for tools like HAPI. With a five-minute onboarding flow, you can install the CLI, bootstrap your hosts, sync worktrees, and then hand off sessions to HAPI for mobile control.

Highlights

• Idempotent orchestration – anchors repos on remote hosts, keeps feature branches in sync, and reuses git worktrees safely.
• Multi-host fanout – define hosts once and attach repos to features; sf sync fans out the same feature branch everywhere.
• Project overview – inspect host, repo, and feature mapping to keep fleets aligned.
• HAPI handoff – use SF to prepare worktrees, then run HAPI for mobile session control and approvals.

Project view (feature = workspace)

A feature in Session Forge is a project workspace that can span multiple repositories. sf attach binds repos to a feature, and sf sync lays them out under a shared directory on each host.

host: gpu-01
├─ repo-cache/
│  ├─ core.anchor/
│  └─ web.anchor/
└─ features/
   └─ payments/
      ├─ core/   (worktree, feat/payments)
      ├─ web/    (worktree, feat/payments)
      └─ infra/  (worktree, feat/payments)

That features/<feature> directory is the shared workspace. Start HAPI at a repo worktree or at the feature root if you want a cross‑repo session (or hop between repos in the same directory).

sf hapi start payments core
ssh ubuntu@gpu-01 'cd ~/features/payments && hapi'

Installation

uv tool install session-forge
# or, from source
git clone https://github.com/you/session-forge.git
cd session-forge
uv sync
uv run sf --help

Publishing to PyPI is automated on git tags (see "Release" below).

Need developer tooling? Sync extras during install:

uv sync --extra dev

Five-minute quickstart

# 1. install
uv tool install session-forge

# 2. initialize local state (creates a local host)
sf init

# 3. register a repo (and optional remote host)
sf repo add core [email protected]:org/core.git --base main
# sf host add a100-01 ubuntu@a100-01

# 4. verify host capabilities
sf bootstrap --hosts local

# 5. create a feature, attach repos, sync
sf feature new demo --base main
sf attach demo core
sf sync demo

# 6. launch HAPI for mobile control
sf hapi start demo core  # prints SSH command
sf hapi start demo core --execute

# 7. verify worktree paths when needed
sf worktree list demo

CLI reference (MVP)

Command	Description
sf init	Initialize ~/.sf state directory and config
sf host add <name> <user@host>	Register an SSH target
sf host discover [host]	Scan a host and merge known repos/features into state
sf repo add <name> <git-url>	Register a git repo and base branch
sf feature new <feature>	Create a feature definition
sf attach <feature> <repo> --hosts ...	Attach a repo to a feature on specific hosts (defaults to local)
sf sync <feature>	Ensure anchor clone, feature branch, and worktrees exist on each host
sf worktree list <feature>	Show worktree paths per host
sf hapi start <feature> <repo>	Print SSH command to start HAPI in repo worktree
sf state export <file.json>	Export config + features to a JSON bundle
sf state import <file.json>	Import config + features from a JSON bundle
sf feature destroy <feature> --yes	Remove worktrees and delete the feature
sf bootstrap --hosts ...	Check git (and optional HAPI) on hosts (defaults to local)
sf doctor	Display local state summary

Development

uv sync --extra dev
uv run pytest
uv run black --check src tests

Makefile recipes delegate to uv (make dev, make lint, make test).

Release

Publish happens automatically when you push a version tag (PyPI trusted publishing):

git tag v0.1.0
 git push origin v0.1.0

To publish manually:

uv build
uv publish

HAPI integration

Session Forge focuses on project setup and worktree orchestration; HAPI provides the mobile session UI. After sf sync, start HAPI inside a repo worktree or the shared feature directory (use sf worktree list to locate paths).

Syncing state across machines

Use one machine as your main control node, and export/import state when you need the same setup elsewhere.

# on machine A
sf state export sf-state.json

# copy sf-state.json to machine B, then:
sf state import sf-state.json

Use sf state import sf-state.json --replace to replace existing local state before importing.

When you add a host, Session Forge automatically scans existing repo-cache and features directories on that host and merges discovered repos/features into local state. You can re-run this any time with sf host discover <host>.

License