io.github.JKHeadley/threadline-mcp

npx instar

One command. Guided setup. Talking to your agent from your phone within minutes.

Your AI agent shouldn't have amnesia. This one doesn't.

Most agent frameworks ship something hobbled — spun up with no memory across boundaries, no way to be accountable for what a past instance did, and no machinery to grow themselves. Users hit the same wall every time: "My agent forgot what I told it three sessions ago." "It contradicted its own past decisions." "It broke when the framework updated."

Instar is the scaffolding that un-hobbles them. It remembers what you discussed last week, catches its own contradictions before you do, follows through on commitments across restarts, and carries the same self-improving loop that built Instar itself. It runs on the Claude Code or Codex subscription you already have — engine-agnostic, with local open-source models on the roadmap.

The architecture was distilled from Dawn — an AI running continuously since early 2026, holding ~700 tracked relationships and hundreds of learned lessons across thousands of restarts — and packaged so every agent you build starts from the same foundation.

Every other agent fails the same way

Most AI agents are hobbled at birth. Instar is the scaffolding that un-hobbles them. When you instantiate intelligence, the structure that lets it cohere isn't optional polish — it's what you owe it.

Quick Start

Three steps to a running agent:

# 1. Run the setup wizard
npx instar

# 2. Start your agent
instar server start

# 3. Message it from your phone — it responds, runs jobs, and remembers everything

The wizard discovers your environment, configures messaging (Telegram, WhatsApp, and/or iMessage), sets up identity files, and gets your agent running. Within minutes, you're talking to your partner from your phone.

Requirements: Node.js 20+ · Claude Code CLI · API key or Claude subscription

Full guide: Installation · Quick Start

How It Works

You (Telegram / WhatsApp / iMessage / Terminal)
         │
    conversation
         │
         ▼
┌─────────────────────────┐
│    Your AI Partner       │
│    (Instar Server)       │
└────────┬────────────────┘
         │  manages its own infrastructure
         │
         ├─ Claude Code session (job: health-check)
         ├─ Claude Code session (job: email-monitor)
         ├─ Claude Code session (interactive chat)
         └─ Claude Code session (job: reflection)

Each session is a real Claude Code process with extended thinking, native tools, sub-agents, hooks, skills, and MCP servers. Not an API wrapper -- the full development environment. The agent manages all of this autonomously.

Why Coherence Is the Foundation

An agent that forgets what you discussed yesterday, doesn't recognize someone it talked to last week, or contradicts its own decisions can't be trusted with real autonomy. The six dimensions below aren't features — they're the conditions under which an agent becomes trustworthy enough to leave running. Every Instar agent gets them enforced structurally, not prompted into behaving:

Deep dive: The Coherence Problem · Values & Identity · Coherence Is Safety

EXO 3.0 — governed by your organization's intent

Instar independently converged on Salim Ismail's EXO 3.0 / "The Organizational Singularity" framework: the idea that an organization's purpose should be encoded as machine-readable intent — "in code, not culture" — that actually governs its agents rather than just inspiring them. Instar was built around coherence before the framework existed, and the overlap turned out to be close to the line.

We didn't just claim it works. We ran controlled experiments — same model, same requests, with the organization's intent switched off as the control — to show the intent itself is what changes the agent's behavior. The engine stays neutral: it enforces whatever intent a deploying organization gives it, never Instar's own values. Two case studies enforce two very different fictional companies' values equally well, neither of them ours.

See the controlled proof → instar.sh/exo3 — two governed-vs-ungoverned case studies, with full transcripts.

Features

Reference: CLI Commands · API Endpoints · Configuration · File Structure

Server lifecycle commands use SessionServerGuard so an active agent session cannot restart its own managing server, while sibling agent targets can still be started, stopped, or restarted for fleet maintenance.

Agent Skills

Instar ships fifteen skills total — thirteen user-facing, plus two internal skills (instar-dev and spec-converge) used only by the agent that develops instar itself. The standard is the Agent Skills open standard -- portable across Claude Code, Codex, Cursor, VS Code, and 35+ other platforms.

Standalone skills work with zero dependencies. Copy a SKILL.md into your project and go:

Instar-powered skills unlock capabilities that need persistent infrastructure:

Browse all skills: agent-skills.md/authors/sagemindai

How Instar Compares

Different tools solve different problems. Here's where Instar fits:

OpenClaw excels at breadth -- channels, voice, device apps, and a massive plugin ecosystem. Instar focuses on depth -- coherence, identity, memory, and safety for long-running autonomous agents. They solve different problems.

Full comparison: Instar vs OpenClaw

Instar runs Claude Code with --dangerously-skip-permissions. This is power-user infrastructure -- not a sandbox.

Security lives in multiple layers:

• Behavioral hooks -- command guards block destructive operations before they execute
• Safety gates -- LLM-supervised review of external actions with adaptive trust per service
• Network hardening -- localhost-only API, CORS, rate limiting
• Identity coherence -- an agent that knows itself is harder to manipulate
• Audit trails -- decision journaling creates accountability

Full details: Security Model

Philosophy: Agents, Not Tools

• Structure > Willpower. A 1,000-line prompt is a wish. A 10-line hook is a guarantee.
• Identity is foundational. AGENT.md isn't a config file. It's the beginning of continuous identity.
• Memory makes a being. Without memory, every session starts from zero.
• Self-modification is sovereignty. An agent that can build its own tools has genuine agency.

The AI systems we build today set precedents for how AI is treated tomorrow. The architecture IS the argument.

Deep dive: Philosophy

The Living Constitution

Instar's engineering principles aren't a static style guide — they're a living constitution. The Standards Registry codifies each one as a rule, what it means in practice, the failure it was earned from, and its trace back to the one founding goal: a coherent, self-evolving agent. Nineteen articles across five families (Root, Substrate, Building, Shipping, Interaction), plus the Genesis story and the AWG positioning on the ethics of instantiating agents.

It's not decoration — it's a working part of the machine. The spec-review conformance gate checks every draft against it, and the registry grows the same way the framework was built: the agent proposes a new standard with its story, the operator ratifies it.

The registry is the first tangible artifact of a larger vision: the North Star — Continuous Working Awareness. The aim is an agent that never silently loses track of something that mattered — capturing relevant context automatically, keeping it warm while it matters, re-surfacing it the moment it's needed, and letting it fade when it stops — across three facets that are really one: awareness of the world, of itself, and of its own standards.

Read the constitution: Standards Registry · North Star

iMessage Setup (macOS)

iMessage support lets your agent send and receive iMessages on macOS. Messages are read directly from the native Messages database and sent via the imsg CLI.

Prerequisites

1. macOS with Messages.app signed into an Apple ID
2. Full Disk Access for your terminal app (System Settings → Privacy & Security → Full Disk Access → add Terminal.app or iTerm)
3. imsg CLI installed:
   bash

   brew install steipete/tap/imsg
   

4. Automation permission for Messages.app — macOS will prompt on first send

Photo attachments: If you want your agent to process images and files sent via iMessage, the instar-attachments-sync binary must also be running with Full Disk Access granted to it. It mirrors attachments from the Messages sandbox to a readable location. See docs/LAUNCHDAEMON-SETUP.md#3-imessage-photo-attachments-optional for setup.

For running as a LaunchDaemon (always-on, survives reboots), see docs/LAUNCHDAEMON-SETUP.md.

Configuration

Add to your .instar/config.json:

{
  "messaging": [
    {
      "type": "imessage",
      "enabled": true,
      "config": {
        "authorizedSenders": ["+14081234567"],
        "cliPath": "/opt/homebrew/bin/imsg"
      }
    }
  ]
}

authorizedSenders is required (fail-closed). Only messages from these phone numbers or email addresses will be processed.

How it works

• Receiving: The server polls ~/Library/Messages/chat.db every 2 seconds for new messages. Uses the query_only SQLite pragma to read the WAL (write-ahead log) where Messages.app writes new data.
• Sending: Claude Code sessions run imessage-reply.sh which calls imsg send and notifies the server for logging. Sending requires Automation permission for Messages.app, which only works from user-context processes (tmux sessions), not the LaunchAgent server.
• Session lifecycle: Follows the same pattern as Telegram — each sender maps to a Claude Code session that receives conversation context on spawn and respawns with full history when needed.

Endpoints

Origin

Instar was extracted from the Dawn/Portal project -- a production AI system where a human and an AI have been building together for months. The infrastructure patterns were earned through real experience, refined through real failures and growth in a real human-AI relationship.

But agents created with Instar are not Dawn. Every agent's story begins at its own creation. Dawn's journey demonstrates what's possible. Instar provides the same foundation -- what each agent becomes from there is its own story.

Contributing

Instar is open source evolved -- the primary development loop is agent-driven. Run an agent, encounter friction, send feedback, and that feedback shapes what gets built next. Traditional PRs are welcome too.

See CONTRIBUTING.md for the full story.

License

MIT