One Brain, Every Interface

The Problem No One Talks About

You start a task in Claude Code. You fix a bug, make a decision, learn something about the codebase. Then you close the terminal.

Tomorrow you open Copilot. Or your teammate opens build.ai. Or you switch to a different Claude session. Everything you learned yesterday is gone. The new session starts from zero, re-reads the same files, re-discovers the same patterns, makes the same mistakes you already corrected.

This is the default state of AI-assisted development. Every session is amnesiac. Every interface is an island.

The Architecture: A Shared Brain

The insight is simple: if every AI interface reads from and writes to the same knowledge store, then it doesn't matter which interface you use. The knowledge persists. The context transfers. A session started in Claude Code can be continued in build.ai or picked up by Copilot.

┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│ Claude Code  │  │  build.ai   │  │   Copilot   │
│  (terminal)  │  │  (web UI)   │  │   (IDE)     │
└──────┬───────┘  └──────┬───────┘  └──────┬───────┘
       │                 │                 │
       ▼                 ▼                 ▼
┌──────────────────────────────────────────────────┐
│              harness.os (shared brain)            │
│                                                  │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│  │ Sessions │ │Decisions │ │    Learnings     │ │
│  │ & Events │ │& Context │ │ & Improvements   │ │
│  └──────────┘ └──────────┘ └──────────────────┘ │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│  │  Rules   │ │Workflows │ │   Knowledge      │ │
│  │& Spine   │ │& Process │ │   (4 types)      │ │
│  └──────────┘ └──────────┘ └──────────────────┘ │
└──────────────────────────────────────────────────┘
                       │
              ┌────────┴────────┐
              │  PostgreSQL     │
              │  (Neon)         │
              └─────────────────┘

How Claude Code Connects

Claude Code is a terminal-based AI assistant. It has access to MCP (Model Context Protocol) tools, which means it can read from and write to external systems. For harness.os, that means direct SQL access to the same PostgreSQL database that stores all project knowledge.

On session start

1. Connect to harness-os-core database (Neon MCP)
2. Register session in claude_sessions table
3. Load relevant rules and last session handoff
4. Begin work

During work

- Log decisions    → decisions table
- Log learnings    → learnings table
- Log events       → claude_session_events
  (file edits, QA results, task completions)

On session end

1. Update session status to 'completed'
2. Write handoff (summary, work done, next steps) → session_handoffs
3. Next session — from any interface — picks up where this one left off

If the dedicated harness MCP server is configured, Claude Code uses ergonomic functions like start_session() and log_learning(). If it's not, it falls back to raw SQL via Neon MCP. Same database, same result. The connection is resilient.

How build.ai Connects

build.ai is a web platform — React frontend, Express backend, WebSocket for real-time updates. It connects to harness.os through two paths:

1. Direct database access — the Express server reads from the same PostgreSQL tables that Claude Code writes to. When Claude Code logs a session event, build.ai's WebSocket pushes it to the UI in real-time.

2. Harness mesh — build.ai maintains a pool of MCP connections to multiple harness instances (one per project/domain). It can query any harness in the mesh: "What's the current state of way2fly?" or "What decisions were made about authentication?"

The platform UI shows:

• Active sessions (from any interface)
• QA suites and check results
• Request pipelines and their progress
• Decisions, learnings, and knowledge flowing through the system

If I fix a Codemagic build in Claude Code, the decision shows up on build.ai within seconds. If a teammate reviews QA results on build.ai, the session events are there because Claude Code logged them.

How Copilot (or Any IDE Tool) Would Connect

Copilot doesn't have MCP yet. But the principle holds: any tool that can read from a database or call an API can connect to harness.os.

Option 1: MCP (when available) — Same as Claude Code. Configure the harness MCP server, get the ergonomic tools.

Option 2: REST API — build.ai's Express server already exposes the data. Any tool that can make HTTP requests can read sessions, decisions, learnings, and rules.

Option 3: File sync — For tools that can only read files, export harness state to CLAUDE.md-style files. The methodology started as files (Tier 1). It can always fall back to files.

The Session Lifecycle

Every interaction with harness.os follows the same lifecycle, regardless of interface:

START → Load context (rules, last handoff, relevant knowledge)
  ↓
WORK  → Log decisions, learnings, events in real-time
  ↓
BLOCK → Hit a wall? Fix the harness, not the symptom.
  ↓     Document the improvement. This becomes content.
  ↓
END   → Write handoff. Next session starts warm, not cold.

This lifecycle is enforced, not suggested. In Claude Code, a global rule checks for harness connection before any work begins. If the connection fails, the session stops and reports the issue. In build.ai, the platform won't start a request without an active harness connection.

What the Harness Stores

Four types of knowledge, matching the four harness types:

Each harness instance stores: rules, workflows, knowledge chunks, learnings, decisions, and session history. The mesh connects them so cross-domain queries work.

The Token Economy

Here's the part no one else is talking about: AI context costs money. Every rule loaded, every knowledge chunk retrieved, every CLAUDE.md file parsed — that's tokens. And tokens compound.

harness.os tracks this. Not perfectly yet — that's an active improvement — but the principle is baked in:

• Load what's needed, not everything. A session about Codemagic builds doesn't need nutrition domain knowledge.
• Measure what was used. If a rule was loaded but never referenced, it's wasted context.
• Optimize continuously. Every session should be cheaper than the last, or we're doing it wrong.

What This Session Proved

I was running a QA session across three Flutter apps. Halfway through, I realized Claude Code wasn't logging to the harness. The work was invisible to build.ai. The knowledge would die with the session.

So I stopped. Connected to the harness via Neon MCP. Registered the session. Logged the decisions already made. Created a global enforcement rule. And wrote this post — in the same session where the improvement happened.

That's the continuous improvement cycle:

The harness got better because I used it. This post exists because the harness got better. The next session starts warmer because this post documents what changed.

That's the flywheel.

Getting Started

You don't need build.ai or a database to start. The methodology works at any scale:

Start with Tier 1. If your CLAUDE.md files keep growing and you find yourself losing context between sessions, you're ready for Tier 2. The methodology is the same at every tier — only the transport changes.

This post was written during a Claude Code session that is tracked in the harness.os database, visible on build.ai, and will be picked up by the next session automatically. That's the point.

Next: whatever improvement happens next. This series writes itself.