nodestone

Document/code checks and layered team views

Bind saved analysis documents to concrete files with document-code-bind, then use document-code-check to compare their current content against a pinned Git commit. The map shows file changes and local code links, with director, manager, team leader and team member presentation layers. See usage and current boundaries.

Trace requirements from source to work

Use nodestone requirement-save requirement.json --expected-version 0 to link a requirement to an exact quote in a saved blueprint brief or analysis field, its acceptance criteria and executable work nodes. nodestone traceability reports uncovered work, unlinked requirements and source/plan drift. Both are available over MCP as requirement_save and traceability_report. Tasks linked to stale requirements require review before lease claim/completion. The map includes a Requirements and sources branch. See the requirement format and review rules.

Cooperative agents and durable handoffs

nodestone task-lease claim next --owner agent-a atomically reserves the next eligible plan task. Use renew, checkpoint, release and complete with the returned token. Completion requires usage evidence references. Checkpoints retain the summary, changed files, evidence and next action across restarts and takeovers. See agent execution workflow for the full protocol, recovery behavior and boundaries. All actions are also available through MCP task_lease. This does not launch agents or lock source files.

Resume a project with an execution briefing

nodestone workflow (MCP: project_workflow) reads the current plan and returns ready, active, waiting, blocked, completed, abandoned and review queues, along with recorded unanswered questions, document draft states and a next action. Waiting tasks include the names and current states of unmet prerequisites. Only executable tasks linked to the saved blueprint enter these queues; unreviewed auto-detected TODOs do not become an execution plan.

The map includes the same What to do now? branch with links back to the original tasks and their acceptance conditions. The briefing is derived from saved records on every call; it does not create a second editable task list. Read it after resuming a session or changing task states. Re-read before starting work: the view itself does not reserve tasks. Use task_lease to coordinate cooperating agents. Dependency readiness does not grant execution permission.

Reported completion of every task leads to needs_acceptance, never automatic product acceptance. Inconsistent prerequisite states lead to needs_reconciliation. Open questions and draft documents remain visible even when work can proceed; the briefing does not infer answers or approve documents.

Resume a project with an execution briefing

nodestone workflow (MCP: project_workflow) reads the current plan and returns ready, active, waiting, blocked, completed, abandoned and review queues, along with recorded unanswered questions, document draft states and a next action. Waiting tasks include the names and current states of unmet prerequisites. Only executable tasks linked to the saved blueprint enter these queues; unreviewed auto-detected TODOs do not become an execution plan.

The map includes the same What to do now? branch with links back to the original tasks and their acceptance conditions. The briefing is derived from saved records on every call; it does not create a second editable task list. Read it after resuming a session or changing task states. Re-read before starting work: this view does not reserve tasks or prevent concurrent agents from taking the same task. Dependency readiness does not grant execution permission.

Reported completion of every task leads to needs_acceptance, never automatic product acceptance. Inconsistent prerequisite states lead to needs_reconciliation. Open questions and draft documents remain visible even when work can proceed; the briefing does not infer answers or approve documents.

Repository navigation and main entry points: Repo rehberi. nodestone/engine/project_map.html is a source template, not an exported map. Open the latest_path returned by nodestone map to view a generated project map.

Save the project's mind map to disk

nodestone --project /path/to/project map exports recorded intent, work hierarchy, dependencies, task states, decisions and analysis drafts to an interactive offline HTML file. Its JSON response includes the absolute path. Open it in a browser to search, navigate branches, read acceptance conditions or switch to a list view. No CDN, server or network is needed. The same operation is available to AI clients through the HTTP and stdio MCP tool project_map_export (no arguments).

Use nodestone map --open to export and open the correct file in your default browser. Combine it with --watch to open once and keep refreshing the saved map. If updating latest.html fails, --open opens the successfully saved snapshot. If the browser cannot start, the export remains available at the printed path.

Default destination: <project>/.nodestone/maps/. With --storage, files go to that memory directory under maps/. Each call atomically saves a new snapshot, preserving previous exports, and refreshes maps/latest.html at a stable path. The response includes latest_path and latest_updated. A failed latest-file update is reported as a warning while the saved snapshot is kept. An unrelated existing latest.html is never silently replaced.

nodestone map --watch keeps that file up to date while the command is running. It polls every two seconds (--interval changes this), exports only after recorded inputs change, and stops with Ctrl+C. No background service is installed. Reload the browser page to see the latest file; the HTML is not a live editor. Concurrent exporters serialize through a separate local lock database, not the event journal. Projects without a blueprint export existing records and show the missing plan. Saved discovery briefs, answers, their source quotes and unanswered questions are included in a separate branch; an answer is not treated as a resolved requirement. Legacy unreviewed TODOs remain a separate branch. Large branches are paged, and search opens the matching record's page. Export checks both the event revision and discovery content so a concurrent change is reported for retry rather than silently mixing versions.

The current branch, selected record, page, zoom, view mode and quick filter are kept in the URL fragment, so reloading latest.html preserves your place without browser storage. Missing records fall back to an existing view with an explanation. Quick filters show explicitly unanswered discovery questions / unknown draft fields and tasks recorded as blocked. These are views of recorded data, not an automatic claim that every unanswered business question has been discovered. Search results include the parent path to distinguish similarly named records.

The HTML contains project content and draft citations in plain text; it is not encrypted storage. Arbitrary project files are not scanned. Task completion does not grant product acceptance.

Project memory for AI sessions. nodestone remembers your project across sessions — decisions, tasks, drift, and context — so an LLM doesn't have to re-learn it from scratch every time. A massiron.com product.

It's an event-sourced cognition store: everything lives on disk and comes back instantly, for ~0 tokens. Pair it with any AI tool (Claude Code, Cursor, OpenCode) over MCP, and your assistant resumes work where it left off.

---

Install

pip install nodestone

Start in 30 seconds

cd your-project
nodestone init                                   # create the project's records (.nodestone/) and print the next steps
claude mcp add nodestone -- nodestone mcp        # connect your AI (Cursor, OpenCode: the same command)
nodestone ui                                     # watch the plan appear while you talk

Then tell your AI what you are building, in your own words. It plans with nodestone: phases, tasks, dependencies and a definition of done, asking you only what you must decide and marking what it proposed itself. When the plan is there, the day looks like this:

nodestone today          # your work and why
nodestone start form     # the task is yours
nodestone done form      # nodestone checks it and says plainly what is still missing
nodestone report         # the status report, from the records only

Nothing is recorded behind your back: asking only reads, and a scan turns to-do comments into suggestions for you to review, never into tasks. Tasks, decisions and completions come only from you, your AI or a check that passed.

Connect it to your AI (MCP)

nodestone speaks MCP over stdio by default — the transport Claude Code, Cursor, and OpenCode launch directly. One command registers it:

claude mcp add nodestone -- nodestone mcp

Restart Claude Code once. Now your assistant can call nodestone natively: restore_context() to resume a project, record_decision(...) to remember a choice, check_drift() to catch scope creep, fingerprint_handoff() to hand the project to another agent.

Prefer HTTP (browser dashboards, LAN)? nodestone mcp --http --host 0.0.0.0 --port 18766.

Free and Pro

Free is the whole product for one person, with no project limit: planning with your AI, completion that nodestone verifies, reports, meetings, project documents, backups. Working alone is not a trial.

nodestone start home     # the task is yours for a working day
nodestone done home      # nodestone checks it and says plainly what is still missing

Pro is for more than one person: adding people with roles and approvals, and using the team server from other computers. It is priced per person, the owner included: $8 a month or $80 a year. nodestone activate buys or renews it in the browser; nodestone activate --file nodestone_license.json uses the license from the purchase email on a computer without a browser. AI clients and services connected with keys take no seat. If Pro ends, nothing is held back: the owner keeps full local access and backups; only adding people and remote sign-in stop. nodestone tier shows where you are.

Everyday commands

nodestone docs                       # every document: unanswered, unconfirmed AI proposals, missing, outdated by code
nodestone classify delivery=mvp multiple_actors=no ai=no   # the project's kind decides which documents it needs
nodestone dependencies               # questions nodestone asks about dependencies the plan left out
nodestone dependencies answer later:form --reason "Built against a mock first"
nodestone ui                         # watch it live in the browser while the AI plans; click anything to inspect
nodestone achievements               # the project as achievements: first picture, scope, delivery, team
nodestone today                      # your work and why: sent back, reopened, ready, waiting, approvals you owe
nodestone work form                  # one task with its context: what done means, decisions, who else touches the files
nodestone start form                 # the task is yours
nodestone start form --file src/api/forms.py   # and these are the files you will change
nodestone touch form src/web/        # more files as you find them
nodestone done form                  # nodestone checks it and says what is still missing
nodestone done form --transcript <file> --note "Built with Claude"   # link the AI conversation the work was done in
nodestone approve form               # a team lead accepts a submission that needs a person
nodestone reject form --reason "The date filter is missing"
nodestone report                     # the status report, from the records only
nodestone proposal submit plan.json --expected-version 3 --reason "API slips a week"
nodestone meeting save notes.json    # what a meeting agreed; feedback on finished work reopens it
nodestone milestone accept m1 --evidence "..."
nodestone scope                      # which areas of the project still lack documents
nodestone login ayse / nodestone logout / nodestone whoami

When two people, or two AIs, are about to change the same files, nodestone says so before any code is written: who holds the other work, which files are shared and since when. The files come from the plan (file checks, code references), from what each holder announced when starting or with touch, and from their checkpoints. A folder covers the files in it, and patterns such as src/api/*.py match. It is a warning, not a lock: the two agree on an order or split the files. The person already working sees it too, in today and in work. AI clients pass files to task_lease and read the answer's warnings.

Every project describes all of its scope areas, but depth follows size. A small project (an MVP one person runs, alone or with their own AI) describes each area with the one document that carries it, 18 or 19 in all; a team or enterprise project fills every core document of every area. A direct answer closes an area (ai=no: nothing to describe about AI use), and an unknown answer never does. The classification is recorded with who set it and why.

Definition of done

A plan states what every task must satisfy across the whole product (for software: each user surface, the documentation, the product language, tests). nodestone does not let the AI forget any of it: every open task covers each item with a check ("covers": ["gui"]) or says in not_applicable why it does not apply, and items with their own check run on every task. The report lists the items skipped as not applicable, so an item that is always skipped stands out.

"definition_of_done": [
  {"id": "english", "text": "All product text is English", "check": {"type": "command", "run": ["python", "-m", "pytest", "tests/test_product_language.py"]}},
  {"id": "docs", "text": "The README shows it"}
]

A team on one server

The project's records live on one team server; everyone else uses the same CLI from their own computer.

# On the server (users come from `nodestone access init` / `access user-add`):
nodestone mcp --http --host 0.0.0.0 --port 18766 --tls-cert server.crt --tls-key server.key

# On a developer's computer:
nodestone --server https://team-server:18766 login ayse
nodestone --server https://team-server:18766 work model
nodestone --server https://team-server:18766 task-lease claim model --owner ayse

NODESTONE_SERVER can replace --server; NODESTONE_SERVER_CA points to the server certificate's CA when it is private. Every call is authorized on the server with the person's role, exactly like AI clients. Commands that need the project's files (maps, scans, init) run only on the server. The server answers requests in parallel; a long check one person runs does not make the others wait.

Reading the AI conversation behind the work

nodestone review form                # the proof and the AI conversation, then approve, send back or leave it
nodestone conversation form          # just the conversation

When work done with an AI is completed, nodestone keeps the part of its conversation from the claim to the completion, so the person approving it reads how it was done, not only the result: what the person asked, what the AI said and one line per tool it used (its output and the AI's private reasoning are left out). API keys, tokens, private keys and passwords are removed. The text is kept next to the journal (conversations.sqlite3); the journal holds its SHA-256, and a reader sees whether it is exactly as recorded. Only the person who did the work, the owners of the plan branches above it and plan admins can read it. The approval notification points at it, the live view shows it on a click, and AI clients read it with work_conversation. With --server, the CLI on the worker's computer sends the conversation with nodestone done, cleaned there and again on the server.

Dates from the real pace

nodestone forecast

Plans start with proposed dates, often the AI's. Once work is being finished, nodestone knows better: it replays how many tasks the project really finishes per day (the last four weeks, days with nothing finished included) against the unfinished work of each open milestone, in date order, and shows the date it lands in half of the runs and in 85 of 100, next to the planned date: on track, at risk or late. The timeline diagram draws it as a bar. A task counts once, so rework does not inflate the pace, and the same records always give the same forecast. With fewer than five finished tasks or three days of history it says so instead of guessing.

Work that does not go at the pace of the rest says so in the plan, and the forecast never places it earlier:

{"id": "pilot", "kind": "task", "name": "A week of real use", "waits_on": "a week of real use", "min_days": 7}

waits_on without min_days (a decision someone has to make) is listed as something the forecast cannot see.

A pilot that measures itself

nodestone pilot                      # the last 7 days
nodestone pilot --since 2026-10-05 --until 2026-10-12 --json

A pilot ends with evidence, not impressions, and nobody keeps a tally by hand. From the records only it shows: work finished and how it was proven (checks, a person's approval, or evidence alone), work reopened or sent back, how long work took from claim to finish, how long submissions waited for a reviewer and what waits now, collisions caught before two people or AIs changed the same files, finished work linked to its AI conversation, notifications delivered, answers people and AIs got from nodestone instead of from a colleague (on a team server with users; otherwise it says it cannot count them), and plan versions, decisions and meetings. It closes with findings: what to look at, in plain sentences.

Telling people what waits for them

nodestone notify set ali --url https://hooks.slack.com/services/...            # ali's Slack
nodestone notify set ayse --url https://....webhook.office.com/... --format teams
nodestone notify set team --url https://hooks.slack.com/services/...           # a room that hears everything
nodestone notify test ali                                                      # does it arrive?
nodestone notify send                                                          # one computer: schedule this

Each person hears, in their own channel, once and in plain English: a submission waiting for their approval (the owner of the nearest plan branch above it), their work sent back with the reason, approved, reopened (for example by meeting feedback), or marked blocked, and someone starting to change files they are changing. The team server sends on its own every 15 seconds (NODESTONE_NOTIFY_SECONDS). A channel only hears what happens after it was set. A broken channel is retried up to five times without holding up the others, and nodestone notify list shows what could not be delivered. Webhook addresses are credentials: they are kept next to the journal, never in it, and listings hide them. People set their own channel, also from their computer with --server; a manager sets anyone's.

Company sign-in (SSO)

People can sign in with their company account instead of a nodestone password. Any OpenID Connect provider works (Entra ID, Google Workspace, Okta, Keycloak): register nodestone there as a public client with device sign-in on.

# On the server, once:
nodestone access sso --issuer https://login.microsoftonline.com/<tenant>/v2.0 --client-id <application id> \
    --domain clinic.example --auto-role member      # --auto-role: newcomers from the company join as members
nodestone access user-add ali@clinic.example --role team_lead --sso   # or add each person yourself

# On a developer's computer:
nodestone --server https://team-server:18766 login --sso   # shows a web address and a code; sign in in any browser

The server checks the provider's answer itself: the ID token's RS256 signature against the provider's published keys, its issuer, audience, lifetime and the allowed domains. Only then does it issue an ordinary nodestone session with the person's role. Someone disabled in nodestone cannot sign in even with a valid company account. --only turns passwords off for the project, and --off turns company sign-in off. ID tokens are never stored, and the audit log records every sign-in and refusal. Without --issuer, nodestone access sso shows the current setup.

GitHub as proof

A task can be finished on GitHub: its plan names a github_pr check, and nodestone reads the pull request and its checks from GitHub itself instead of trusting what a person or an agent reports.

{"id": "api", "kind": "task", "name": "Appointment API",
 "checks": [{"type": "github_pr", "repo": "clinic/api", "required_checks": ["tests", "lint"]}]}

nodestone done api --pr 12          # or --commit <sha>: nodestone finds the pull request that contains it

The task completes only when the pull request is merged and every required check is green; otherwise nodestone says what is missing. With other checks on the same task, files and commands are verified on the merge commit. Access is your own (GITHUB_TOKEN, GH_TOKEN or gh auth login); for proof nodestone only reads, and only for tasks with this check. Without repo, the project's origin remote is used; NODESTONE_GITHUB_API points at GitHub Enterprise Server.

Handing a task to a GitHub agent

nodestone github handoff api --base-branch main   # opens an issue with the task's context, assigned to Copilot
nodestone github sync                             # reads GitHub: completes merged work, gives back abandoned work

The issue carries what the task is, when it is done and the decisions that apply. The task is held by github:copilot, so nobody works on it twice, and it completes only when the linked pull request is merged and the task's github_pr check passes, the same proof a person's work needs. A pull request closed without merging gives the task back. The assignee hands off their own task; a team lead any task in their branch. --custom-agent and --model are passed to GitHub unchanged.

The plan as GitHub issues

nodestone github mirror --dry-run   # what would change; nothing is sent
nodestone github mirror             # every plan task as an issue in the origin repository (or --repo owner/name)

Each issue shows the task's status (as a nodestone: <status> label), phase, owner, done criteria and the issues it needs first, with a link back to the task. Finished work closes its issue. The mirror runs one way: nodestone stays the record, and a title, body or state edited on GitHub is put back on the next run without touching the plan. Comments, assignees and your own labels are left alone. An issue a task was handed to an agent on keeps the agent's instructions. Publishing the plan needs plan.write.

Backup, restore and external AI

nodestone backup office-2026-09-29.zip            # consistent even while the team server runs
nodestone --storage /srv/new restore office-2026-09-29.zip
nodestone restore office-2026-09-29.zip --replace  # current records are set aside, never deleted

Every file in the archive is checked against its manifest before anything is restored. The archive holds the access registry's password hashes: store it like a password file.

An API key in the environment is not consent. ask and llm generate send nothing to an AI provider until the project owner or a plan admin runs nodestone ai-consent allow <provider> --reason "...". The decision is recorded and can be revoked; AI clients cannot grant it through nodestone's tools.

Self-introduce to every AI editor

nodestone inject all

Writes a short nodestone block into CLAUDE.md, AGENTS.md, .cursorrules, and friends, and registers the MCP server in ~/.claude.json and opencode.json. Idempotent — re-run any time. Remove with nodestone inject all --remove.

---

The massiron family

nodestone is one of four local tools that compose:

• nodestone — project context memory across sessions (this tool)
• atlas — deterministic code intelligence (call graph, risk, dead code), 0 LLM tokens
• deepstrain — autonomous engineering agent, a cheap fast executor
• adauto — developer-marketing automation, ethics-filtered + human-approved

Each works standalone and introduces the others when installed.

Project interview and connected planning (source implementation)

Start with nodestone discover begin "your project description". The interview asks about the user, problem, vision, mission, outcomes, success criteria, scope, quality, constraints and unknowns. nodestone discover next "answer" records an answer; discover start resumes without erasing earlier answers. Empty answers are rejected. An AI client can provide already-known answers with exact quotes using --known or the discovery_begin MCP tool. Quote validation establishes provenance, not semantic correctness: interpretation and contradiction handling still require AI/client review.

nodestone blueprint context exposes the existing interview and work-tree schema to the planning AI. blueprint save plan.json --expected-version 0 imports a structured plan; subsequent edits use its current version. Vision, mission, goals, work sections, milestones, tasks and prerequisites are validated together. The journal stores the plan and executable tasks atomically. This is an explicit structured import, not an automatic natural-language planner or evidence-based completion engine.

blueprint show returns the task tree and mind map from the same record. Task statuses are read live; changed intent, ancestors or prerequisites invalidate affected completed work. blueprint show --html new-plan.html exports an offline mind map and collapsible tree. Export is a snapshot; render again after changes. Existing task removal/conversion to a group is currently rejected rather than silently losing history.

nodestone status is now scan-free and concise. Legacy untouched auto-detected to-do tasks remain in history but are separated from planned work. status --json exposes integrity counts; status --full retains the detailed legacy analysis. suggestions scan detects TODOs as review candidates, suggestions list shows them and suggestions accept ID accepts one idempotently. Python comments are tokenized; other supported source suffixes currently scan full-line // comments. These detections do not prove the work is required.

Stdio MCP honors --storage and no longer edits external client configuration at startup. Client registration remains an explicit setup step. MCP is included in runtime dependencies. The source implementation still needs packaged-install, real AI interview, recovery and customer acceptance before any sales-readiness claim.

Source-linked analysis selection

nodestone blueprint context --profile profile.json returns the interview and plan alongside a proposed analysis set. Example profile: {"delivery":"enterprise","confidential":"yes","ai":"yes","multiple_actors":"yes"}. Omitted fields stay unknown. The same optional analysis_profile object is accepted by the HTTP and stdio planning_context tools.

The bundled catalog distinguishes templates, guides, examples and proposed adaptations. Selection does not generate completed documents, grant data-sharing permissions, or establish product acceptance. The profile is a read-only call input and is not persisted as project policy.

Fillable analysis drafts

Use nodestone analysis template PA-001 to retrieve an original field guide and an example JSON payload. Fill the payload with explicitly typed statements and observations. Anything nobody stated must be labeled ai_proposal with a basis; drafts that carry unlabeled content are refused, and the report counts AI proposals until a person confirms them. unknown is only for answers a proposal would fabricate (measurements, research results) and needs a basis saying why. Check it with nodestone analysis check draft.json, then save with nodestone analysis save draft.json --expected-version 0. Read it with nodestone analysis show PA-001; add --markdown for a human-readable snapshot.

The MCP tools are analysis_template, analysis_draft_check, analysis_draft_save, and analysis_draft_view. Drafts preserve versions and reject stale changes; filling all fields means ready for review, never accepted. Citation matching checks caller-supplied excerpts, not source authenticity or semantic correctness. Storage is not encrypted. These are original Nodestone field guides, not verbatim third-party templates.