Metadata-Version: 2.1
Name: swfte-nexus-harness
Version: 0.1.0
Summary: The fleet plane over every coding-agent harness — list, start, and hand off governed agent sessions.
License: LicenseRef-Proprietary
Author: Swfte AI
Project-URL: Homepage, https://www.swfte.com
Project-URL: Product, https://www.swfte.com/products/nexus
Project-URL: Documentation, https://www.swfte.com/docs
Project-URL: Support, https://www.swfte.com/support
Project-URL: Issues, https://www.swfte.com/contact
Keywords: agents,cli,governance,observability,claude-code,codex
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Nexus Harness

**One place to run, govern, and move work across every coding-agent harness your team uses.**

Nexus Harness is the fleet plane for coding agents. Claude Code, Codex, Gemini CLI, Cursor,
opencode, amp and the rest each keep their own sessions, their own history and their own idea of
what a unit of work is. Nexus Harness puts one surface over all of them: a single list of every
session, one way to start a governed one, and one way to move a piece of work from one harness to
another without losing what it was for.

- **Product overview** — <https://www.swfte.com/products/nexus>
- **Documentation** — <https://www.swfte.com/docs>
- **Support** — <https://www.swfte.com/support>
- **Contact** — <https://www.swfte.com/contact>

---

## Install

```bash
pip install swfte-nexus-harness
```

The command is `nexus-harness`. It requires Python 3.10 or newer and has **zero runtime
dependencies** — nothing but the standard library. That is deliberate. This is a developer
terminal tool that gets installed with `pipx`, with `uv tool install`, or into whatever
interpreter happens to be first on `PATH`. Every dependency is a version range that can conflict
with yours, and a conflict at install time is where adoption ends. It is also the tool you reach
for when the rest of the stack is broken, and a diagnostic that cannot start because one of *its*
dependencies failed to resolve is worse than no diagnostic at all.

Verify the install:

```bash
nexus-harness --version
nexus-harness doctor
```

---

## Start with `doctor`

`doctor` is the command to run first, and the one that tells you the truth:

```
ok    nexus binary        …/nexus (nexus 0.3.0)
ok    harness registry    2/6 harnesses can host a governed session (claude, codex)
FAIL  collector read API  collector not reachable at http://127.0.0.1:8791
                          fix: `nexus collector` to start it
WARN  harness codex       hooks not installed yet
FAIL  harness opencode    Nexus has no hook installer — a session here would run uninstrumented
WARN  harness opencode    registry row is an unverified seed
```

Every failure line carries the fix. Note that there are **three** states, not two. A gap that is
not a fault reports `WARN` and never `ok`, because an unverified registry row printed under a
green `ok` renders an absence as if it were fine — and that is precisely the class of bug this
product exists to prevent.

---

## Sign in (optional)

Every command below works signed out. Signing in attributes sessions to your workspace and your
user, so the fleet view, the cost figures and the audit trail belong to somebody rather than to a
machine.

```bash
nexus-harness login              # opens your browser, approve the device, done
nexus-harness connect <code>     # no browser: redeem a setup code from your dashboard
nexus-harness whoami             # who this machine is signed in as (never prints the key)
nexus-harness logout             # revoke the credential, then delete it locally
```

`login` is the usual road. `connect` is the same destination by a different one, and the only
one available where no browser can be opened — a CI runner, a fleet image, an ssh session on
somebody else's box.

The credential is written to `~/.nexus/credentials.json` at `0600`. It is the **same** file the
`nexus` CLI writes, in the same format, so signing in with either tool signs in both. One
credential, not two.

`doctor` reports being signed out as a `WARN`, not a `FAIL` — it is a real gap worth naming, but
nothing here is broken because of it.

These four commands are the only ones that reach off your machine, and they only do so when you
type them. There is no telemetry, no licence check-in and no update ping. See
[SECURITY.md](SECURITY.md).

---

## The four capabilities

### Fleet

See every session across every harness in one table — which are governed, which are not, and
why. Start a new one on any harness that Nexus can instrument.

```bash
nexus-harness harnesses          # what is installed, what can be governed
nexus-harness sessions           # the fleet view
nexus-harness sessions --live    # only what the control plane confirms is alive now
nexus-harness start codex        # launch a governed session
```

### Handoff

Move a unit of work from one harness to another — carrying the objective, the plan, the
completion gates, the files touched and the cost — without losing lineage.

```bash
nexus-harness handoff <session-id> --to claude
```

### Roles

Bind a model, a provider and a harness to a job: Claude for planning, Codex for coding, another
model for testing. The routing is a property of the work, not of whichever terminal you happened
to open.

### Workflows

Turn recurring work into ordered, role-bound plans. Workflows are advisory first — they propose,
they do not seize the wheel.

These are deliberately one product rather than four features. A workflow step boundary, a role
transition and a handoff are **the same edge**. Built separately they would disagree about what a
unit of work is, and the audit trail would fragment at exactly the boundaries where it matters.

---

## What it will not do

**It never reports a session as governed when it is not.** A harness can be installed and on your
`PATH` and still be impossible to instrument. Nexus Harness shows that difference loudly rather
than quietly counting the session as covered.

**It never renders absence as zero.** Cost from a harness with no readable transcript is
*unknown*, not free. `unknown` and `0` never share a pixel.

**It degrades honestly.** If the Nexus binary is missing or the collector is down, every command
still runs and names precisely what is unavailable and how to fix it. An ungoverned session that
says so is acceptable. A session that reports itself governed while capturing nothing is the
failure the whole product exists to prevent.

---

## Requirements

| | |
|---|---|
| Python | 3.10, 3.11, 3.12 or 3.13 |
| Platform | macOS (Apple Silicon or Intel), Linux x86-64 or arm64, glibc or musl |
| Runtime dependencies | none |
| Nexus binary | required for governed sessions; every command degrades without it |
| Collector | optional; `doctor` reports its absence rather than failing |

The wheels are platform-tagged, because each one carries a compiled executable rather than Python
source. On a platform not in that list `pip install` reports **"could not find a version that
satisfies the requirement"** — which reads like the package is missing or the name is wrong, so it
is worth naming the real cause here.

**Windows is not published yet.** It ships as its own release with its own signed artifacts rather
than being folded into this one. This is release sequencing, not a portability limit.

The desktop application is a separate download for macOS and Linux. See
<https://www.swfte.com/products/nexus>.

---

## Licence and support

Nexus Harness is proprietary software, licensed and not sold. Copyright © 2026 Swfte. All rights
reserved. See the bundled `LICENSE` for the full terms, and
<https://www.swfte.com/terms> and <https://www.swfte.com/privacy>.

For help, a licence question, or a bug report, contact us at
<https://www.swfte.com/contact> — we do not run a public issue tracker.

Swfte — <https://www.swfte.com>
