Humans and AI together

Nexa's workspace and candidate model was built so that two attempts at the same task can coexist instead of colliding. That turns out to fit a person and an AI tool working the same branch, which is what this page describes. It was designed for parallel work generally, not for AI specifically — a distinction worth keeping, because it is the reason the model is available today.

Rinko Hub does not run AI agents

This page describes a filesystem and CLI arrangement that humans and AI tools can both use. Rinko Hub does not run, host, schedule or orchestrate AI agents for anyone, and there is no agent API. Whatever AI tooling you use, you run it yourself. See What is not built.

The candidate substrate

Three implemented properties are what make parallel attempts safe. Each is a protocol behaviour, not a policy or a convention.

Separate contexts mean separate files. Implemented A working context is one repository, one branch and one workspace materialized as its own directory. Two contexts on the same branch in different workspaces have independent working files, so neither can write over the other's work in progress.

A workspace isolates work within a branch. Implemented Workspaces are where competing versions of a branch live — one workspace per problem, one version per attempt. Recording in one workspace does not alter another, so two participants can record at their own pace.

A branch holds competing candidates, and selecting one does not delete the others. Implemented This is the part that differs most from a pointer-based model. A branch keeps the set of candidates offered to it; choosing one marks it selected and supersedes the rest without discarding them. A rejected attempt remains in the repository and can be examined or chosen later.

Why this matters for review

Because selection is a reference rather than a property of the version, comparing two attempts and changing your mind later costs nothing and destroys nothing. The alternative you did not pick is still there.

What this looks like in practice

Give each participant its own context on the same branch. The person works in one directory, the AI tool in the other, and the root shows both:

Command

$ nexa contexts

Expected output

LOCAL	REPOSITORY	BRANCH	WORKSPACE
RinkoHub	local:~/src/RinkoHub	development	human
RinkoHub-auth	local:~/src/RinkoHub	development	auth-agent

Both rows are the development branch of one repository, in the workspaces human and auth-agent. Each has its own working files. From here, each side records its own versions independently with nexa record.

Two flags matter when the work is an attempt rather than an answer. --candidate records a version without selecting it, which is the honest default for an unreviewed attempt — it offers the work without asserting it is the accepted state:

Command

$ nexa record -p RinkoHub-auth -m "Rework the token refresh" --candidate

Expected output

Recorded as a candidate, not selected. Choose it with:
  nexa version select d597ad555bc9 --workspace auth-agent

--parent bases a version on a specific parent rather than on the current selection, which is how a second attempt starts from the same point as the first instead of building on it.

Reviewing then means listing the candidates in a workspace with nexa version list, comparing them, and choosing with nexa version select. Selecting does not discard: the previous selection remains a candidate. Where two lines of work should become one, Nexa's merge is available per its currently implemented behaviour, reporting conflicts by path and object identity.

Nothing above is AI-specific. It is the same mechanism a pair of people would use to try two approaches, which is exactly why it is dependable for this: it is exercised by ordinary collaboration rather than by a special path reserved for tools.

What is not built

The model above is suitable for humans and AI tools using the same filesystem and CLI primitives. It is not an agent platform, and the following do not exist.

Agent orchestration. Planned Nothing runs, schedules, supervises or coordinates AI agents. There is no agent API and no way to hand Rinko Hub a task to be carried out.
Agent identity and attribution. Planned There is no way to register an agent, attribute a version to one as distinct from a person, or record the prompt that produced it.
Scoped agent capabilities. Planned Granting a participant a restricted set of permissions — read source but not secrets, record versions but not merge to a main branch — is designed and not implemented.

These are deliberately the last phase of protocol work, and the constraint on them is already enforced ahead of their existence: the engine's own test suite fails if the core ever takes a dependency on an agent crate. AI support must remain a leaf that can be removed without affecting whether the protocol stores objects, merges or synchronises.

Attribution today

Because agent identity is not implemented, a version recorded by a tool you run is recorded under the identity you ran it with. If you need to tell human and tool work apart, the reliable signal today is which workspace it was recorded into — so give each participant its own, as above, and use the --author flag deliberately.