Agent NextUp

An AI session is short and forgetful; a real project is long and full of context. Most of the friction in working with agents comes from that mismatch — every new session starts by re-deriving what the last one already knew, and whatever never got written down is simply gone.

Agent NextUp keeps that context in files the engine keeps fresh. You make the decisions, your agent does the work, and a handoff stays possible at every moment.

What it organises

Any body of work — software, research, a side business, life planning — into four things:

• Project — a folder you chose. Every piece of state is a file you can open, diff, and commit.

• Tasks — atomic units of work, each small enough to finish in one session, with a status and optional prerequisites.

• Phases and gates — the project moves through phases from a template (the generic one runs plan → execute → review → retrospect), and each phase has exit gates the engine evaluates against real state.

• Handoff snapshot — "where things stand and what comes next", regenerated by the engine on every state change. A new session, a new machine, or a different person reads one file and picks up the thread.

Related MCP server: Brain OS

Features

• Files are the whole product. No database. Snapshots and search indexes are rebuildable derivatives; the ledger is append-only and is the audit record. If Agent NextUp vanished tomorrow, your project would still be readable.

• Gates you cannot mark yourself. min_tasks(n), all_tasks_done, artifact_exists(path) and the rest are computed from disk, never self-reported. manual_confirm is the inverse — only a human can satisfy it, and no tool exists for an agent to do so. Forcing any gate demands a reason and is written to the ledger. (the full set)

• A handoff that is never stale. The snapshot regenerates on task, decision, milestone, and phase changes, so it is never older than your last action.

• Claimed done is not done. Completing a task records a claim; verification is a separate mark that requires evidence, and the bulk archive sweep collects only verified work, deliberately leaving the rest on the list where you can see it.

• Agent reach is an allowlist. One master switch decides whether agents reach the hub at all; with it on, read-only tools need no further setup, and writes are authorised per tool, with the gatekeeping ones off by default. Every call — including denied ones — lands in the ledger.

• Parallel agents can't jump the queue. Give tasks an assignee and prerequisites and the engine refuses out-of-order starts and finishes. Claims cannot be stolen.

• A terminal that runs the real CLIs. A genuine PTY process per agent CLI, rooted at the workspace. Sessions belong to the app, so switching projects doesn't interrupt them, and a running terminal can pop out into its own window.

• Projects can feed each other. Wire workspaces into a directed graph and one project delivers to another's inbox, with attachments. An agent can publish but never route — routing is a human action, or a per-edge automation a human switches on. Inbox content is defined as data, not instructions.

• A spec layer that stays current. specs/<capability>/spec.md records what the system does now; task bundles hold the deltas, and archiving a verified task folds its delta into the main spec. The folding is enforced; writing the delta is prompted by the agent's operating protocol.

• Search and portable backups. Full-text search over the workspace (language-agnostic chunking into an SQLite FTS5 index), and export/import of the management layer — tasks, specs, ledger and handoff material — as a zip you can carry to another machine. Your own source files are not in it: they travel with the folder, or with git.

How it works

A managed workspace is an ordinary folder. Abridged to the parts you will actually open:

my-project/
  AGENTS.md            entry point + engine-maintained state block
  project.yaml         phase / progress / updated, synced line by line
  nextup_docs/          operating guide for a headless session
  memory/              cross-session memory, one fact per file
  .mcp.json            hub connection for the agent host
  .nextup/
    workflow.json      phases, AI instructions, exit gates, position
    agent_access.json  per-tool authorisation
    ledger.jsonl       append-only event ledger
    snapshots/latest_handoff.md
  tasks/  artifacts/
  specs/               only when the specs module is on

The entry point is AGENTS.md — the filename agent hosts look for; Claude Code gets there through a one-line CLAUDE.md shell. The engine rewrites the fenced block on every state change and never touches anything you hand-write outside it:

<!-- NEXTUP:STATE:BEGIN -->
> ⚙️ Maintained automatically by the Agent NextUp engine (hand edits are overwritten on the next update); updated 2026-07-29T09:52:38Z

**Status**: Demo project (domain: coding) — 2 tasks: 1 todo / 1 in progress / 0 blocked / 0 done; current phase **Spec** (1/5, template Software Development).

**Instructions for this phase**:
- Read the handoff and context.json, then shape the requirements into a verifiable spec.
- Break the implementation into atomic tasks (with acceptance criteria) under tasks/.
- Record key technical choices (framework, data structures, boundaries) as decisions.

**Exit gates** (evaluated by the engine against real state):
- [x] min_tasks(1) — 2/1
- [x] min_decisions(1) — 1/1

**Next steps** (up to 5; ▶ = in progress):
- ▶ [P0] T-0001 — Design the data model
- · [P2] T-0002 — Write the user documentation

**Blockers**: none right now.

**Recent decisions**:
- `2026-07-29T09:52:38Z` Files are the source of truth; the index can always be rebuilt
<!-- NEXTUP:STATE:END -->

That block is real output, not a mock-up: cargo run -p nextup-core --example gen_demo -- <dir> en produces it.

Delete the markers and the engine stops touching the file entirely. Continuity is a guarantee you can revoke.

Both listings above are abridged. The authoritative account of what lands on disk, which files are the truth and which are rebuildable derivatives, is the disk contract.

Quick start

Download an installer from the latest release:

Nothing is code-signed, so the first launch raises an unknown-publisher warning: SmartScreen on Windows, Gatekeeper on macOS. Nothing updates itself either — a newer version means coming back here for it.

Prerequisites — Rust (stable, MSVC toolchain on Windows), pnpm, and WebView2 on Windows 10. You don't need to manage Node: the repo pins the version and pnpm fetches it.

git clone https://github.com/white1024/agent-nextup.git
cd agent-nextup
pnpm install
pnpm tauri build     # the first build takes a while

The installer lands under target/release/bundle/. If you are developing, pnpm tauri dev runs the app without installing.

Then:

1. Create a project — launch the app, choose Initialize new project, pick a folder, name it, pick a workflow template, and tick any capability modules you want (collaboration, teams, specs — all off unless you tick them). Templates ship built in for software, research, business, life planning, and anything else; drop a JSON file into ~/.nextup/templates/ to add your own, with no recompilation.

2. Connect an agent (optional) — authorise the write tools you want on the Tools page, then open your agent CLI in the project folder.

Full walkthrough: install → first project → connect an agent.

Documentation

User-facing documentation is the project website, at https://white1024.github.io/agent-nextup/. It is the source of truth — this README links to it rather than repeating it, and the pages below are the whole of it.

Architecture at a glance

React 19 + TypeScript UI
        |  Tauri IPC
src-tauri/            thin delivery layer
crates/nextup-core/    domain core, zero Tauri dependencies
crates/nextup-mcp/     hub MCP server (stdio), spawned by the agent host

The core has no Tauri dependency, so the same operations layer serves both the GUI and the hub. An agent and the app can write concurrently because every mutation takes the same cross-process lock; a file watcher pushes the agent's changes back into your window. The layer diagram, the event names and the module map are in reference/architecture.

Development

pnpm tauri dev                  # run the app in development
pnpm build                      # typecheck + build the web layer
pnpm test                       # frontend unit tests (vitest)
cargo test --workspace          # must be fully green before committing

See reference/building for the test suite, packaging, and the unsigned-build notes, and CONTRIBUTING.md for the repository layout, the layering rules enforced under src/, and how a change reaches this repository.

Status

In active development. v0.1.0 is the first pre-release: unsigned trial builds for three platforms, with no auto-update yet.

Working — the workspace engine and disk contract; the phase/gate harness and its built-in templates; the handoff layer; the hub MCP server with per-tool authorisation; the embedded agent terminal, including custom CLI entries carrying environment variables, which is how you point one at a local model; adopting an existing project through a wizard that analyses read-only and never overwrites; milestones; full-text search; portable backups. As opt-in modules: collaboration, teams and cross-project delivery, and the spec layer.

Not there yet — signed installers and auto-update; in the teams module, automatic "a delivery arrives → a task is created" (turning one into a task manually is one click today), and scheduling.

License

MIT.