session-forge 0.1.4
Session Forge (sf): orchestrate remote worktrees and project setup for HAPI-managed sessions.
License: Apache-2.0
Requires Python: >=3.10
Keywords: cli, ssh, git, worktree, hapi

# 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](https://github.com/tiann/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.

```text
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).

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

## Installation

```bash
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:

```bash
uv sync --extra dev
```

## Five-minute quickstart

```bash
# 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 git@github.com: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

```bash
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):

```bash
git tag v0.1.0
 git push origin v0.1.0
```

To publish manually:

```bash
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.

```bash
# 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

Apache License 2.0