Northstar

An editable software-improvement decision workspace where humans and browser agents turn source-linked evidence, constraints, and trade-offs into a human-owned Improvement Plan.

Comment

Inspiration

AI coding tools can help non-developers build software, but deciding what should change next is still difficult. In an ordinary chat, hypotheses, counter-evidence, constraints, rejected options, and trade-offs become buried across messages. The AI may produce an answer, but the human cannot easily inspect or revise the decision that produced it.

Northstar explores a different interface: a shared, visual software-improvement decision that both a person and a browser agent can work on.

The controlled prototype starts with a familiar problem: “I built a RAG chatbot, but the answer quality is poor.”

What it does

Northstar turns software-improvement reasoning into an editable workspace. A person can:

  • inspect competing explanations and the evidence behind them;
  • add supporting or contradicting evidence;
  • mark an approach as already tried;
  • reject or deprioritize hypotheses;
  • activate constraints;
  • compare improvement alternatives by benefit, complexity, cost, latency, and risk; and
  • select a preferred direction.

The actual output is not a chat transcript. It is a structured Improvement Plan containing the problem, important evidence, selected explanation, selected improvement, rejected options and reasons, constraints, risks, implementation steps, and acceptance criteria.

Why WebMCP

WebMCP makes the workspace meaningfully better because the human and agent operate on the same structured decision state.

The page exposes eight semantic tools:

  • inspect_improvement_workspace
  • list_code_files
  • read_code_file
  • add_evidence
  • update_hypothesis
  • record_decision
  • begin_analysis
  • complete_analysis

A browser agent can inspect the current decision, read shared source files with numbered lines, add only source-linked evidence, and complete a review. Human changes—such as counter-evidence, rejected options, and active constraints—become inputs to the agent's next analysis instead of remaining trapped in a separate conversation.

The agent cannot silently take ownership of the decision. An agent-selected alternative remains a proposal until the human confirms it.

How we built it

Northstar is a React and Vite single-page application deployed on Vercel. The site registers its tools with document.modelContext.registerTool().

Human controls and WebMCP tools dispatch domain actions into the same reducer state. Presentation components derive the diagnosis, recommendation, alternatives, and Improvement Plan from that state. Tool contracts validate revisions, decision ownership, source file IDs, and exact one-based line ranges.

The prototype intentionally has no backend, database, external API, or site-owned LLM. Code context and decision state remain in browser memory. The page supports controlled sample files as well as pasted or uploaded text-based source files.

Human and agent workflow

  1. Parsing begins as the strongest explanation because several failed examples involve tables.
  2. The human adds counter-evidence: failures also happen on plain-text PDFs.
  3. The human marks prompt changes as already tried, rejects multimodal parsing because of cost, and activates a simplicity constraint.
  4. A browser agent reconsiders the current revision through WebMCP.
  5. The agent verifies claims against exact source line ranges and updates the shared decision.
  6. Retrieval becomes the leading explanation and a reranker becomes the recommended experiment.
  7. The human reviews the trade-offs, chooses the direction, and receives an updated Improvement Plan.

Challenges

The hardest design problem was avoiding a chatbot, admin dashboard, or RAG monitoring interface. The core visual object needed to remain a decision.

We also had to make agent activity trustworthy. Northstar tracks code-context and decision revisions, hides stale recommendations, requires exact source ranges for source-derived evidence, and prevents an agent recommendation from masquerading as a human selection.

Accomplishments that we're proud of

  • A coherent human-facing product experience, not only a tool-registration demo.
  • Eight working WebMCP tools mapped to domain concepts instead of UI button clicks.
  • Source-linked evidence with exact file and line ranges.
  • Visible revision and analysis states that prevent stale conclusions from appearing current.
  • A human confirmation boundary around the preferred improvement direction.
  • A structured Improvement Plan that can be reviewed without reading an agent transcript.

What we learned

WebMCP is most valuable when tools expose the meaning of an application rather than imitate mouse interactions. The agent does not need to guess how the UI works, and the human does not need to translate every judgment back into a prompt. Both can collaborate through the application's domain model while the interface preserves context and ownership.

What's next for Northstar

This submission is deliberately a controlled RAG prototype, not a universal code analyzer. Next steps would include persisted decisions, broader project-context adapters, reusable decision templates, and integrations with development tools—while keeping source edits and final direction explicitly under human control.

Built With

Share this project:

Updates

Submission history