Skip to content
/
Tier B A10 Memory engine

IM.codes

im-codes · im4codes/imcodes · ★ 100 · last commit 2026-05-26

Primitive shape
No installable primitives
00

Summary

IM.codes — Summary

IM.codes is a self-hosted, three-tier "instant messenger for AI coding agents" that bridges your mobile phone, web browser, and desktop terminal to any number of running coding agent sessions (Claude Code, Codex, Gemini CLI, OpenClaw, Qwen). The core architecture is: browser/mobile → WebSocket → self-hosted server → WebSocket → daemon on the dev machine → tmux/transport → agent process. Beyond remote terminal access it provides a shared vector-memory layer (pgvector, multilingual embeddings), turn-level auto-supervision (judge completed turns as complete/continue/ask_human), P2P multi-agent discussion pipelines where agents cross-audit each other's plans, and an imcodes send agent-to-agent messaging bus with circuit breakers. It is distributed as an npm package (imcodes) with three binaries: imcodes (daemon CLI), imcodes-launch, and imcodes-launch-preflight; the companion server is Docker-deployed (PostgreSQL + Caddy). Compared to the seeds, IM.codes most closely resembles claude-flow in its MCP-anchored toolserver orientation and multi-agent coordination, but differs fundamentally by operating entirely outside the agent's process: it is a side-channel control and memory layer rather than a prompt or tooling framework injected into the agent's context.

01

Overview

IM.codes — Overview

Origin

IM.codes is a personal open-source project by a single developer (1 contributor on GitHub). It was built almost entirely using Claude Code, with contributions from Codex and Gemini CLI — the "dog-food" origin story is prominent in the README. Active development as of 2026-05-26.

Philosophy

"IM.codes keeps those sessions within reach from mobile or web: open the terminal, inspect files and git changes, preview localhost from another device, get notified when work finishes, and keep multiple agents moving on your own infrastructure."

"It is not another AI IDE or a generic remote terminal. It is the messaging/control layer around terminal-based coding agents."

"What IM.codes is not: Not another AI IDE. Not just a chat wrapper. Not just a remote terminal client. Not a replacement for Claude Code, Codex, Gemini CLI, OpenClaw, or Qwen. It is the messaging/control layer around them."

The project explicitly frames itself as infrastructure plumbing, not an agent-methodology framework. The agent still runs where it always ran (tmux/terminal); IM.codes adds remote visibility and control without interrupting the native workflow.

Self-Hosting Emphasis

"Self-hosting is strongly recommended. The shared instance at app.im.codes is for testing only — it comes with no uptime guarantees, may be rate-limited, and could be targeted. This is a personal project with no commercial support."

Disclaimer

"There are no warranties, no SLA, and no guarantees of stability, security, or backward compatibility. Use at your own risk. Breaking changes may happen at any time without notice."

Target Problem

When developers step away from their desk, terminal-based coding agent sessions become invisible and uncontrollable. IM.codes solves this gap by providing mobile + web remote control without requiring SSH, VPN, or port forwarding — specifically for the scenario where agents run on personal dev machines, not cloud VMs.

02

Architecture

IM.codes — Architecture

Distribution

  • npm package: npm install -g imcodes
  • Server: Docker Compose (PostgreSQL pgvector + Node.js/Hono backend + Caddy reverse proxy)
  • Mobile: iOS/iPadOS app on the App Store; Android not mentioned
  • Web: PWA at app.im.codes or self-hosted

Three-Tier System

You (browser / mobile / Apple Watch)
        ↓ WebSocket
Server (Node.js + Hono + PostgreSQL/pgvector, self-hosted)
        ↓ WebSocket
Daemon (Node.js CLI on user's machine, src/)
        ↓ tmux (Linux/macOS) / ConPTY (Windows)
AI Agents (Claude Code / Codex / Gemini CLI / OpenClaw / Shell / Script)
        ↔ imcodes send (agent-to-agent)

Directory Structure (repo)

src/           — Daemon (Node.js/TypeScript)
  agent/       — Two backends: process (tmux/ConPTY) + transport (network SDK)
    drivers/   — claude-code.ts, codex.ts, gemini.ts, opencode.ts, shell.ts
    providers/ — qwen.ts (LOCAL_SDK), openclaw.ts (PERSISTENT WebSocket)
  bind/        — Daemon bind flow (server registration)
  cli/         — CLI subcommand implementations
  daemon/      — server-link.ts, transport-relay.ts
  router/      — message-router.ts, command-parser.ts
  store/       — session-store.ts (JSON at ~/.imcodes/sessions.json)
  autofix/     — auto-fix loop
  context/     — context injection
  tracker/     — session tracking
server/        — Self-hosted backend (Node.js + Hono)
  routes/      — server.ts, passkey-auth.ts, push.ts, cron-api.ts, discussions.ts
  ws/bridge.ts — WsBridge: daemon ↔ browser relay
  db/          — PostgreSQL migrations
web/           — Browser frontend (React)
mobile/        — iOS/Android (React Native or similar)
landing/       — Static landing page assets

Required Runtime

  • Node.js >= 22 (daemon)
  • tmux (Linux/macOS) OR ConPTY built-in (Windows 10+)
  • Docker (server self-hosting)
  • PostgreSQL with pgvector extension (server)
  • At least one agent CLI: claude, codex, gemini, opencode, qwen, openclaw

Target AI Tools

Claude Code, Codex, Gemini CLI, OpenClaw, Qwen, OpenCode, GitHub Copilot, Cursor (and more via process or transport backends)

Install

npm install -g imcodes
imcodes bind https://app.im.codes/bind/<api-key>
# or self-host:
imcodes setup --domain imc.example.com

Key Config Files

  • ~/.imcodes/server.json — server binding credentials
  • ~/.imcodes/sessions.json — persistent session store (debounced JSON)
  • .env (Docker) — PostgreSQL + server secrets
  • docker-compose.yml — generated by imcodes setup
03

Components

IM.codes — Components

CLI Binaries

Binary Purpose
imcodes Main daemon CLI (bind, status, send, upgrade, setup, connect, disconnect)
imcodes-launch Shell launcher script
imcodes-launch-preflight Windows launch preflight checker

CLI Subcommands (from README + src/index.ts)

  • imcodes bind <url> — Register daemon with a server, start as system service
  • imcodes setup --domain <domain> — One-command self-hosted server + daemon setup
  • imcodes send <target> <message> [--reply] — Agent-to-agent message dispatch
  • imcodes connect openclaw [--url ...] — Connect OpenClaw transport gateway
  • imcodes disconnect openclaw — Remove OpenClaw connection
  • imcodes upgrade — OTA daemon self-upgrade via npm
  • imcodes repair-watchdog — Repair Windows watchdog/scheduled task

Daemon Modules (src/)

Module Purpose
agent/drivers/claude-code.ts Process driver for Claude Code sessions (tmux/ConPTY)
agent/drivers/codex.ts Process driver for Codex sessions
agent/drivers/gemini.ts Process driver for Gemini CLI sessions
agent/drivers/opencode.ts Process driver for OpenCode sessions
agent/drivers/shell.ts Generic shell session driver
agent/providers/qwen.ts Transport provider: Qwen (LOCAL_SDK, stream-json)
agent/providers/openclaw.ts Transport provider: OpenClaw (PERSISTENT WebSocket)
agent/detect.ts Agent type detection
agent/session-manager.ts Session lifecycle, auto-restart with loop prevention
agent/provider-registry.ts Transport provider lifecycle management
daemon/server-link.ts WebSocket client to server's /api/server/:id/ws
daemon/transport-relay.ts Converts transport callbacks to timeline events
router/message-router.ts Routes inbound messages to correct session
router/command-parser.ts Parses /bind, /status, /send, etc.
store/session-store.ts JSON persistence at ~/.imcodes/sessions.json
autofix/ Auto-fix loop logic
context/ Context injection
tracker/ Session tracking

Server Routes (server/routes/)

Route Purpose
server.ts WebSocket upgrade + session management
passkey-auth.ts WebAuthn passkey registration/login
push.ts Push notifications (APNs iOS + FCM Android)
cron-api.ts Scheduled task CRUD
discussions.ts P2P discussion runs/history
file-transfer.ts File upload/download
session-mgmt.ts Session label/description/cwd CRUD

Features (product-level)

Feature Description
Remote Terminal Full PTY streaming at 12fps, raw or structured chat view
File Browser Tree + git status, per-file diff, upload/download
Localhost Preview WebSocket tunnel to proxy dev server traffic
Auto Supervision Turn-level judge: complete/continue/ask_human
Supervised Audit Optional audit→rework loop before session returns
P2P Discussions Multi-agent cross-provider audit/review pipelines
Streaming Transport SDK-backed agents (Claude Code SDK, Codex SDK)
Agent-to-Agent imcodes send with depth/rate/broadcast circuit breakers
Scheduled Tasks Cron-style task scheduling via UI
Repository Dashboard Issues, PRs, branches, CI/CD status
Apple Watch Unread counts, quick replies from wrist
Discord-style Sidebar Server icon bar, hierarchical session tree

Database Tables (PostgreSQL)

users, servers, sessions, sub_sessions, passkey_credentials, passkey_challenges, api_keys, scheduled_tasks, orchestration_runs

05

Prompts

IM.codes — Prompts

IM.codes is primarily an infrastructure/transport layer rather than a prompt framework. The prompting content is in the auto-supervision and P2P discussion engines, not in exported prompt files. The CLAUDE.md is a developer guide, not a behavioral prompt.

Excerpt 1: CLAUDE.md — Architecture description (developer-facing)

From CLAUDE.md:

IM.codes is a specialized instant messenger for AI coding agents — a three-tier system for remote terminal access, file browsing, multi-agent workflows, and session management:

You (browser / mobile app)
        ↓ WebSocket
Server (Node.js + Hono + PostgreSQL, self-hosted in server/)
        ↓ WebSocket
Daemon (Node.js CLI on user's machine, src/)
        ↓ tmux / ConPTY / transport
AI Agents (Claude Code / Codex / Gemini CLI / OpenClaw / Shell)
        ↔ imcodes send (agent-to-agent)

Prompting technique: Architectural specification — provides mental model for the codebase rather than behavioral instruction for an agent.

Excerpt 2: Auto-Supervision Description (README behavioral spec)

From README:

Instead of blindly continuing forever, IM.codes evaluates the latest completed turn and decides 
whether the task looks done, should keep going, or should come back to you. For higher-assurance 
work, supervised_audit can automatically trigger an audit/rework loop before the session is 
considered finished.

...

Auto is also aware of IM.codes-native workflows such as OpenSpec changes, P2P discussions, 
and imcodes send, so those actions count as legitimate next steps instead of accidental 
"ask human" triggers.

Prompting technique: Role-based judgment prompt — a supervisor is instructed with a global persona + per-session override, evaluating turns as complete/continue/ask_human. This is an LLM-in-the-loop supervision pattern, not a static prompt file.

Excerpt 3: P2P Discussion Modes (README)

From README:

Built-in modes include audit (structured audit → review → plan pipeline), review, discuss, 
and brainstorm — or define your own phase sequence.

Prompting technique: Multi-turn structured pipeline — each agent receives all prior contributions as context and adds its own perspective. Cross-provider adversarial review.

Note on Prompt File Availability

No standalone prompt .md files were found in .claude/commands/ or similar locations in this repo. The supervision and discussion prompts are compiled into the server/daemon JavaScript and configurable via the web UI at runtime. This is architecturally different from a skills-based framework where prompts are human-readable markdown files.

09

Uniqueness

IM.codes — Uniqueness

differs_from_seeds

IM.codes is closest to claude-flow among the seeds in that both provide multi-agent coordination, persistent memory (vector-based), and an MCP-anchored or transport-anchored control layer. However, the architectural delta is fundamental: claude-flow injects its tooling into the agent's context via MCP tools and prompt-chaining, so the agent actively calls claude-flow's APIs. IM.codes operates outside the agent's process entirely — it monitors tmux output via terminal scraping, routes keystrokes back in, and provides supervision via a separate LLM call at turn boundaries. The agent remains unmodified, running exactly as it always did; IM.codes is a side-channel. The closest seed for the memory subsystem is ccmemory (Neo4j + vector), but IM.codes adds supervised execution, mobile remote control, and cross-provider agent messaging on top. No seed in the corpus addresses the "left-desk mobile continuity" problem.

Positioning

IM.codes occupies a unique position as remote-control infrastructure for agent sessions, not an agent framework. It solves the last-mile problem: agents run fine on the developer's machine, but become invisible and uncontrollable when the developer moves. IM.codes addresses this without requiring any changes to the agent tool or workflow. It is the only framework in this batch with an Apple Watch client.

Observable Failure Modes

  1. Self-hosted complexity: requires Docker, a domain, DNS, certificates — real ops burden for a personal dev tool
  2. Single maintainer: 1 GitHub contributor, personal project disclaimer, no SLA
  3. Terminal scraping fragility: process-backed agents rely on terminal pattern detection to infer agent state (status, waiting-for-input) — changes to agent output format break heuristics
  4. Breaking changes: explicit disclaimer that "breaking changes may happen at any time without notice"
  5. Windows experimental: ConPTY path is marked experimental
  6. PostgreSQL dependency: server requires pgvector extension; adds maintenance surface

What Is Genuinely Novel

  • Apple Watch + mobile + web + terminal remote control in a single product
  • imcodes send agent-to-agent bus with depth/rate/broadcast circuit breakers
  • Turn-level auto-supervision (complete/continue/ask_human judgment at idle boundaries) as a configurable daemon feature, not a prompt pattern
  • Multilingual vector memory shared across agent sessions and devices
  • Scheduled tasks (cron) targeting specific agent sessions
04

Workflow

IM.codes — Workflow

Setup Phase

Step Artifact
npm install -g imcodes Daemon binary installed
imcodes setup --domain <domain> (self-hosted) docker-compose.yml, .env, server running
imcodes bind <url> ~/.imcodes/server.json created, daemon registered as system service
Open web/mobile app Session list appears

Normal Session Workflow

  1. Developer starts agent in terminal (e.g. claude in a tmux window)
  2. Daemon detects session via tmux monitoring
  3. Session appears in IM.codes sidebar on mobile/web
  4. Remote user monitors output, sends messages, views file changes, previews localhost
  5. Auto-supervision (if enabled) evaluates completed turns and continues autonomously or returns control
  6. Notifications fire when agent completes or needs input

Auto-Supervision Modes

Mode Behavior
off No automation — user drives all turns
supervised Evaluate each turn: complete / continue / ask_human
supervised_audit Evaluate + trigger audit→rework loop before releasing

P2P Discussion Workflow

  1. Configure participants (provider A + provider B + mode)
  2. Each agent reads all prior contributions and adds its perspective
  3. Built-in modes: audit (structured pipeline), review, discuss, brainstorm
  4. Ring progress indicator shows round/hop completion
  5. Multiple rounds with configurable max

Agent-to-Agent Communication

imcodes send "Plan" "review the changes in src/api.ts"
imcodes send "Cx" "run tests" --reply
imcodes send --all "migration complete, check your end"

Circuit breakers: depth limit, rate limiting, broadcast cap.

Approval Gates

IM.codes has no formal approval-gate framework for coding specs. The supervision system is the closest equivalent: the ask_human decision returns control at turn boundaries. All approvals come via mobile/web UI interaction.

Phase → Artifact Map

Phase Artifact
Bind ~/.imcodes/server.json
Session start ~/.imcodes/sessions.json entry
Turn completion Timeline events in PostgreSQL (orchestration_runs)
Auto-supervision decision Structured JSON dispatch back to agent
P2P discussion Discussion history in PostgreSQL (discussions table)
Scheduled task Cron entry in scheduled_tasks table
06

Memory Context

IM.codes — Memory & Context

Memory Architecture

IM.codes has the most sophisticated memory system in this batch. It is a hybrid of local vector search + server-side PostgreSQL/pgvector + optional cloud sync.

What Is Stored

  • Only final assistant.text outputs are materialized. Streaming deltas, tool calls, and intermediate noise are excluded.
  • Processed summaries can optionally sync to a user-scoped cloud pool shared across devices.
  • Teams can publish reusable memory into workspace/project scopes.

Storage Layers

Layer Technology Scope
Session store JSON file ~/.imcodes/sessions.json Process-local daemon
Server DB PostgreSQL (pgvector/pg18) All sessions, cross-device
Vector index pgvector with multilingual embeddings Semantic recall
Timeline events PostgreSQL orchestration_runs table Audit log

Multilingual embeddings (supports English, Chinese, Japanese, Korean, Spanish, Russian, mixed-language repos). Both local semantic search and server-side pgvector recall.

Context Injection

  • Relevant past work is injected per-message and at session startup.
  • Timeline cards show what was recalled, why (relevance score, recall count, last-used time).
  • User can inspect, query, archive/restore processed summaries via the Shared Context UI.

Session Persistence

  • Thread bindings and read offsets survive daemon restarts (~/.imcodes/sessions.json).
  • Cross-session handoff: yes — sessions persist in PostgreSQL; new devices see existing sessions.

Compaction

No explicit compaction mechanism described. Memory summarization happens as a background processing step (raw events → processed summaries).

State Files

  • ~/.imcodes/server.json — Server binding credentials
  • ~/.imcodes/sessions.json — Session state (debounced JSON writes)
  • ~/.imcodes/openclaw.json — OpenClaw connection config
  • ~/.imcodes/watchdog.log — Windows watchdog log
  • ~/.ccbot/session_map.json — (CCBot companion, not IM.codes itself)
  • PostgreSQL: users, servers, sessions, sub_sessions, api_keys, scheduled_tasks, orchestration_runs, discussions
07

Orchestration

IM.codes — Orchestration

Multi-Agent Support

Yes. IM.codes is designed for running multiple agent sessions simultaneously, with explicit inter-agent coordination:

  • Each session is independently managed (tmux windows or transport connections)
  • imcodes send enables explicit agent-to-agent messaging
  • P2P discussions coordinate multiple agents in structured review pipelines

Orchestration Pattern

Hierarchical + parallel-fan-out hybrid

  • Normal sessions: parallel fan-out (N agents running independently, monitored via sidebar)
  • P2P discussions: sequential multi-round pipeline where each agent reads all prior contributions
  • Auto-supervision: hierarchical (supervisor evaluates each agent's turn)

Isolation Mechanism

Process isolation via tmux panes (Linux/macOS) or ConPTY (Windows). Each session is an independent OS process. No git worktrees or containers managed by IM.codes itself — agents operate in their own directories.

Execution Mode

Continuous-background-daemon. The daemon runs as a system service (registered via imcodes bind), not as a one-shot CLI.

Multi-Model Support

Yes. IM.codes supports any mix of Claude, Codex, Gemini, OpenClaw, Qwen, OpenCode agents running simultaneously. The supervision backend (judge model) can be configured separately from the working agents. No hard-coded model routing — each session specifies its own agent type.

Consensus Mechanism

None formal. P2P discussions are pipeline-style (each agent adds its perspective), not Byzantine/raft consensus. The output is synthesized by reading all contributions.

Agent-to-Agent Communication

imcodes send with:

  • Target resolution by label, session name, or agent type
  • --reply flag for automatic response routing
  • Circuit breakers: depth limit, rate limiting, broadcast cap (prevents cascade loops)
imcodes send "Plan" "review the changes in src/api.ts"
imcodes send "Cx" "run tests" --reply
imcodes send --all "migration complete, check your end"

Auto-Supervision Execution

At turn boundaries (agent goes idle), the supervision backend:

  1. Reads the completed turn's output
  2. Classifies as complete | continue | ask_human
  3. If continue: dispatches a continuation prompt into the same session
  4. If supervised_audit: triggers audit pipeline, sends rework brief back
  5. If ask_human or timeout/invalid: returns control to user

Configuration is two-layer: global supervision persona (re-read every turn) + per-session override.

08

Ui Cli Surface

IM.codes — UI & CLI Surface

CLI Binary

  • Name: imcodes
  • Type: Own runtime daemon (not a thin wrapper over claude/codex)
  • Package: npm install -g imcodes
  • Subcommands: bind, setup, send, connect, disconnect, upgrade, repair-watchdog
  • Also exposes imcodes-launch (shell script) and imcodes-launch-preflight (Windows)

Local UI

IM.codes has the richest UI surface in this batch:

Web App (self-hosted or app.im.codes)

  • Full terminal emulator (PTY streaming at 12fps)
  • Structured chat view with parsed tool calls and thinking blocks
  • File browser with tree view, git status, diff viewer
  • Localhost preview (WebSocket tunnel)
  • Repository dashboard (issues, PRs, CI/CD)
  • Scheduled tasks with visual cron picker
  • P2P discussion view with ring progress indicator
  • Shared Context UI (query, preview, archive/restore memory)
  • Discord-style sidebar with session tree and unread badges
  • 7 languages (i18n)
  • Port: configured by Docker/Caddy — no hardcoded port

Mobile (iOS/iPadOS App Store)

  • Full terminal with interactive keyboard
  • Biometric authentication
  • Push notifications (APNs)
  • Sub-session preview cards
  • File upload (photos, images)
  • Toast navigation to relevant session

Apple Watch

  • Session monitoring
  • Unread counts
  • Quick replies

IDE Integration

None. IM.codes is explicitly not an IDE or IDE extension.

Observability

  • Timeline cards show memory recall (what was recalled, why, relevance score)
  • Daemon error forwarding to browser via WebSocket daemon.error events
  • Server logger redacts tokens/keys/secrets before output
  • PostgreSQL orchestration_runs table as audit log for P2P discussions and auto-supervision

Cross-Tool Portability

High — supports Claude Code, Codex, Gemini CLI, OpenClaw, Qwen, OpenCode, GitHub Copilot, Cursor as agent backends. Any tmux-based agent or transport-backed agent can be connected.

Related frameworks

same archetype · same primary tool · same memory type

MemPalace ★ 53k
A10 Memory engine

Verbatim local-first AI memory with 96.6% R@5 retrieval on LongMemEval using zero API calls — structured into a palace hierarchy…

Beads (Yegge) ★ 24k
A10 Memory engine

Dolt-powered distributed graph issue tracker where AI agents track tasks with hierarchical IDs and dependency edges, claim work…

deepagents (LangChain) ★ 23k
A10 Memory engine

Opinionated Python agent harness on top of LangGraph with sub-agents, filesystem, memory, and context compaction bundled in

agentmemory ★ 18k
A10 Memory engine

Persistent, searchable memory for AI coding agents that captures every tool interaction, compresses it via LLM, and injects…

Open Multi-Agent ★ 6.3k
A10 Memory engine

Give a natural-language goal to a coordinator agent and get a dynamically decomposed, parallelized task DAG executed by…

Basic Memory ★ 3.1k
A10 Memory engine

Gives AI agents a persistent, human-readable knowledge graph of project decisions, observations, and relations stored as plain…