instar

Persistent Claude Code agents with scheduling, sessions, memory, and messaging.

npm · GitHub · instar.sh · Docs

npx instar

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

Instar turns Claude Code from a powerful CLI tool into a coherent, autonomous partner. Persistent identity, memory that survives every restart, job scheduling, two-way messaging (Telegram, WhatsApp, iMessage), and the infrastructure to evolve.

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

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.

Claude Code is powerful. But power without coherence is unreliable. An agent that forgets what you discussed yesterday, doesn't recognize someone it talked to last week, or contradicts its own decisions -- that agent can't be trusted with real autonomy.

Instar solves the six dimensions of agent coherence:

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

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

Instar ships 12 skills that follow 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

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

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.

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:

   brew install steipete/tap/imsg

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

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.

• 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.

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.

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.

MIT