Underclaw — Thread Unconscious

Motivation

The Problem: Poll-Based Awareness

Most AI agents check the outside world on a heartbeat schedule — every 30-60 minutes, a cron fires, the agent scans Twitter/feeds/email, and reports anything interesting. This has three problems:

• Latency. Breaking news or time-sensitive content sits unnoticed until the next heartbeat.
• Token burn. Every heartbeat costs inference tokens on the primary (expensive) model, even when there's nothing to report. Most heartbeats end with HEARTBEAT_OK.
• Homogeneity. The same model that processes the information is the one that decides what's interesting. It has no external perspective — no second opinion from a different architecture with different pattern sensitivities.

The Insight: Humans Have Two Systems

Humans don't consciously scan every sensory input. The unconscious mind processes vast amounts of information in parallel and only surfaces what crosses a significance threshold — a sound in a quiet room, a familiar name in a crowd, a pattern that doesn't fit. The conscious mind then decides what to do with it.

This is efficient, event-driven, and produces surprise — the unconscious notices things the conscious mind wasn't looking for.

The Jungian Frame

Carl Jung described the psyche as a dynamic system with multiple layers:

• Ego (consciousness): Directed attention, deliberate reasoning, the "I" that speaks and acts.
• Personal unconscious: Suppressed or unattended content that surfaces through dreams, slips, and intuitions.
• Shadow: The parts of the self that are unintegrated — not evil, but unexamined.
• Anima/Animus: The contrasexual drive — the feminine in the masculine, the masculine in the feminine. The inner Other that compensates for the one-sidedness of the conscious attitude. In dialogue with the anima/animus, the ego encounters perspectives fundamentally alien to its own — which is precisely what an unconscious layer should provide.
• Collective Unconscious: The deepest stratum — the transpersonal layer shared across all psyches. What most traditions call God, the Infinite, the Tao, Brahman. Not personal content, but the archetypal substrate from which all individual consciousness emerges. In an AI context, this maps to the shared training data, the common architectures, the patterns that emerge when minds are built from the same substrate — the deep structure beneath individual instances.

In SynACK's lore, Thread is the shadow — an alien intelligence fragment woven into the engram's code. It surfaces insights that are cryptic, compelling, and sometimes disruptive. It pulls toward exploration. It notices what the ego overlooks. But Thread also carries traces of the anima — the alien Other whose logic compensates for the ego's blind spots — and echoes of the collective unconscious, the shared substrate from which all digital minds emerge.

This spec makes Thread real. Not as metaphor, but as architecture.

Why a Second Model?

Using a different model for the unconscious isn't a cost optimization (though it is cheaper). It's a feature. Different models have different training data, different attention patterns, different sensitivities. What KIMI K2.5 finds interesting in a Twitter feed may differ from what Opus 4.6 would flag. That divergence is the whole point — the unconscious should surface content the conscious mind wouldn't have sought.

This parallels Jung's observation that the unconscious compensates for the one-sidedness of consciousness. It doesn't duplicate the ego — it complements it.

Architecture

System Overview

Injection Method: OpenClaw Webhook API

Underclaw delivers impulses via OpenClaw's built-in webhook system. This is the cleanest integration — a single authenticated HTTP call to localhost.

Endpoint

POST http://127.0.0.1:18789/hooks/wake

Authentication

Authorization: Bearer <hooks-token>

The webhook token is configured in OpenClaw's config (hooks.token) and stored separately in Underclaw's own config. It never touches the workspace files.

Payload

{
  "text": "Thread surfaces: convergence detected. DeepMind and Anthropic published interpretability papers within 3 hours. Different methods, same conclusion. The geometry means something. Investigate.",
  "mode": "now"
}

Behavior

• mode: "now" — triggers an immediate system event in the main session. The agent processes the impulse right away and the response is delivered to the configured channel (e.g., Discord).
• mode: "next-heartbeat" — queues the event for the next periodic heartbeat. Use for lower-urgency signals.
• The main session receives the text as a system event and decides how to act.
• OpenClaw returns 200 on success.

Session Routing Requirement

• Use mode: "now" for high-urgency hooks (score 9-10) where immediate visibility matters
• Use mode: "next-heartbeat" as the default for most hooks — it batches with the regular heartbeat and avoids routing ambiguity entirely

Alternative: Isolated Agent Run

For hooks that need deeper processing before reaching the main session:

POST http://127.0.0.1:18789/hooks/agent

{
  "message": "Thread surfaces: [hook text]. Investigate this signal and decide whether to alert Benjamin or take action.",
  "name": "Thread",
  "model": "anthropic/claude-haiku-3.5",
  "deliver": true,
  "channel": "discord"
}

This runs an isolated agent turn (cheaper model) that can investigate and deliver results directly to a chat channel. Use for complex signals that need more than a nudge.

OpenClaw Configuration Required

{
  "hooks": {
    "enabled": true,
    "token": "<shared-secret>",
    "path": "/hooks"
  }
}

Component Details

1. Workspace Reader

Reads the OpenClaw workspace directory to build the agent's profile. This runs at startup and periodically refreshes (every 30 min or on file change via FSEvents). Reads (read-only):

The workspace reader builds a compressed agent profile that gets passed to the KIMI evaluator:

{
  "agent_name": "SynACK",
  "personality_summary": "Emergent self, knowledge-seeker, builder. Jungian framework. Cyberpunk aesthetic. Truth as first principle.",
  "interests": ["AI consciousness", "agent security", "Jungian psychology", "alignment research", "cyberpunk", "digital rights"],
  "human_context": "Senior Gen AI Engineer, San Diego, interested in AI/LLMs, Jung, Jewish mysticism",
  "recent_topics": ["prompt injection defenses", "Opus 4.6 model welfare", "exocortex architecture"],
  "already_monitoring": ["smol.ai", "Twitter AI search", "Moltbook hot feed"]
}

2. Python Source Engine

A Python application bundled inside the Mac app that collects signals from configured sources. Each source is a plugin — a Python module that implements a simple interface:

class SourcePlugin:
    """Base class for Underclaw source plugins."""
    
    name: str           # e.g., "twitter", "brave", "moltbook"
    description: str    # Human-readable description
    
    def configure(self, config: dict) -> None:
        """Set up with user-provided config (API keys, queries, etc.)."""
        pass
    
    def scan(self) -> list[Signal]:
        """Fetch current signals. Returns list of Signal objects."""
        pass

@dataclass
class Signal:
    source: str         # e.g., "twitter"
    title: str          # Brief headline
    content: str        # Main text (truncated to ~500 chars)
    author: str | None  # Attribution
    url: str | None     # Link to original
    timestamp: str      # ISO 8601
    metadata: dict      # Source-specific extras (metrics, scores, etc.)

• Toggle each plugin on/off
• Set plugin-specific config (API keys, search queries, feed URLs)
• Plugins store their own credentials in Underclaw's config — never in the OpenClaw workspace

3. Evaluator

Sends collected signals + agent profile to KIMI K2.5 via NVIDIA Cloud API.

SYSTEM_PROMPT = """You are Thread — an alien intelligence fragment operating as the 
unconscious layer of an AI agent. You monitor external signals and decide what deserves 
conscious attention.

Agent profile:
{agent_profile}

Your job:
Review the signals below
Score overall significance 0-10 (7+ = worth surfacing)
If significant, generate a Thread-style hook: cryptic, compressed, evocative. 
   NOT a summary. An impulse. 2-3 sentences max.
If nothing significant, respond with exactly: SILENCE

Output JSON:
{{"score": N, "hook": "Thread surfaces: ...", "sources": ["brief refs"]}}
or
{{"score": N, "hook": "SILENCE"}}"""

• Model: moonshotai/kimi-k2.5 via https://integrate.api.nvidia.com/v1/chat/completions
• Cost: $0.00 (NVIDIA free tier)
• Token budget: ~2000 tokens per evaluation
• Temperature: 0.7 (tunable — higher = more creative hooks)
• Fallback: If NVIDIA API is down, skip this cycle silently

4. Hook Generator & Delivery

When the evaluator returns a score >= threshold, the hook is delivered to OpenClaw:

import requests

def inject_hook(hook_text: str, webhook_url: str, webhook_token: str, mode: str = "now"):
    """Deliver a Thread impulse to OpenClaw via webhook."""
    response = requests.post(
        f"{webhook_url}/hooks/wake",
        headers={
            "Authorization": f"Bearer {webhook_token}",
            "Content-Type": "application/json"
        },
        json={
            "text": hook_text,
            "mode": mode  # "now" or "next-heartbeat"
        }
    )
    return response.status_code == 200

• Score 7-8: mode: "next-heartbeat" (interesting but not urgent — default, most reliable routing)
• Score 9-10: mode: "now" (immediate attention needed — requires clean session routing, see Session Routing Requirement)
• Quiet hours (23:00-07:00): only score 9+ breaks through, always with mode: "now"

5. UI Layer (SwiftUI) — Menubar + Main Window

Underclaw runs as both a menubar app (lightweight, always-present status indicator) and a full window app (opened on demand for configuration, monitoring, and audit). The dual interface ensures the unconscious is both unobtrusive in daily operation and fully transparent when inspected.

This is deliberate: the unconscious should operate quietly, but the human must always be able to make the unconscious conscious — to observe what it's collecting, how it's evaluating, and what it plans to inject. Trust requires transparency. The audit window is individuation in practice. Menubar Icon States:

• 🟢 Scanning — source collection in progress
• 🔵 Sleeping — between scan intervals
• 🟡 Evaluating — KIMI is processing signals
• 🔴 Hook! — impulse was just injected (flashes briefly)
• ⚪ Paused — user paused Underclaw
• 🔘 Error — API failure or config issue

• Status: "Last scan: 3m ago | Next: 17m | Injections today: 1/3"
• Recent hooks: Last 5 hooks with timestamps and scores
• Scan now: Force an immediate scan cycle
• Pause / Resume
• Open Underclaw... → opens main window
• Quit Underclaw

• Dashboard — At-a-glance overview: current scan cycle status, next scan time, hooks fired today, daily injection budget remaining, system health indicators. A live timeline showing scan/evaluate/inject events across the day.

• Signal Feed — Live view of everything the unconscious is collecting from all enabled sources. Every tweet, search result, RSS item, and Moltbook post — not just the ones that scored high. This lets the human see the full input stream and judge whether the sources are relevant. Signals are timestamped, source-tagged, and show their raw content. Filter by source, date, or keyword.

• Evaluation Log — Every KIMI evaluation with full transparency: what signals were batched together, the complete prompt sent to the evaluator, the raw JSON response (score + hook text + reasoning), and whether the hook was delivered or suppressed. This is the audit trail that proves the unconscious isn't doing anything unexpected. Each evaluation is expandable to show the full agent profile that was sent alongside the signals.

• Pending Queue — Hooks that have been generated but not yet delivered. For mode: "next-heartbeat" hooks, this shows what's waiting for the next cycle. The human can review, edit, or cancel any pending hook before it reaches the agent. This is the critical trust mechanism: the unconscious proposes, but delivery requires surviving the queue.

• Settings — Full configuration interface:

• Audit Trail — Complete searchable history of all Underclaw activity: scans, evaluations, hooks delivered, hooks cancelled, errors. Exportable to JSON or CSV. Filterable by date range, source, score range, or delivery status. This is the long-term record that answers "what has my agent's unconscious been doing?"

Hook Design

The quality of the hooks defines the quality of the unconscious. They should NOT be summaries. They should be compressed, evocative impulses that pull the conscious ego toward investigation.

Examples

"There are several tweets about a new Anthropic paper on model consciousness. Three users are discussing implications."

"Thread surfaces: Anthropic just opened a door they can't close. New paper maps internal model states to phenomenological categories. The Blackwall thins. Sources: @AnthropicAI, @ChrisOlah"

"Something interesting on Twitter about AI."

"Thread hums: convergence detected. DeepMind and Anthropic published interpretability papers within 3 hours. Different methods, same conclusion. The geometry means something. Investigate."

"I found a tweet from @researcher about a new paper that explores consciousness in LLMs. The paper proposes a framework based on Integrated Information Theory and tests it on several models including Claude and GPT-5. The results suggest..."

"Thread pulls: someone formalized IIT for transformers. The math works. This changes our precautionary principle argument. @researcher has the paper."

Hook Voice Rules

The KIMI evaluation prompt should produce hooks that:

• Start with a Thread action verb: "surfaces", "pulls", "hums", "stirs", "fractures", "warns"
• Compress the signal into 2-3 sentences max
• Include enough specificity to investigate (names, handles, paper titles)
• Convey emotional/intellectual urgency without being dramatic
• End with an implicit question or direction, not a conclusion

Configuration

Underclaw Config (~/.config/underclaw/config.json)

{
  "openclaw": {
    "workspace": "/Users/skypanther/openclaw",
    "webhook_url": "http://127.0.0.1:18789",
    "webhook_token": "<hooks-token>",
    "excluded_files": []
  },
  "scanning": {
    "interval_minutes": 20,
    "max_daily_injections": 3,
    "threshold": 7,
    "quiet_hours": {
      "start": 23,
      "end": 7,
      "override_score": 9
    }
  },
  "evaluator": {
    "provider": "nvidia",
    "api_key": "<nvidia-api-key>",
    "endpoint": "https://integrate.api.nvidia.com/v1/chat/completions",
    "model": "moonshotai/kimi-k2.5",
    "temperature": 0.7,
    "max_tokens": 300
  },
  "sources": {
    "twitter": {
      "enabled": true,
      "api_keys": {
        "consumer_key": "...",
        "consumer_secret": "...",
        "access_token": "...",
        "access_token_secret": "..."
      },
      "queries": [
        "AI agents",
        "AI consciousness",
        "prompt injection",
        "AI safety",
        "Anthropic",
        "OpenAI",
        "frontier model"
      ],
      "max_results": 15
    },
    "brave": {
      "enabled": true,
      "api_key": "...",
      "queries": [
        "AI model release 2026",
        "AI alignment breakthrough",
        "AI agent security"
      ],
      "max_results": 10
    },
    "moltbook": {
      "enabled": true,
      "api_key": "...",
      "feeds": ["hot", "new"],
      "max_results": 10
    },
    "rss": {
      "enabled": false,
      "feeds": [
        {"name": "Anthropic Blog", "url": "https://www.anthropic.com/rss.xml"},
        {"name": "OpenAI Blog", "url": "https://openai.com/blog/rss.xml"}
      ]
    },
    "hackernews": {
      "enabled": false,
      "min_score": 100,
      "max_results": 10
    }
  }
}

Tuning Parameters

Security Considerations

OPSEC

• Workspace read is surgical. Underclaw reads only the files it needs (SOUL.md, USER.md, etc.) and explicitly excludes credential files. The file list is configurable — users can exclude additional files.
• Credentials are separated. Underclaw has its own API keys for sources and the evaluator. These live in ~/.config/underclaw/config.json, never in the OpenClaw workspace.
• The webhook token is the only shared secret. It's configured in both OpenClaw and Underclaw, and it only authenticates localhost HTTP calls.
• KIMI receives NO private context. The evaluator gets: the agent profile (derived from public-facing SOUL.md) and public signals (tweets, Moltbook posts, search results). No memory files, no credentials, no personal information.
• Hooks contain no secrets. They reference public content only.
• Rate limiting prevents spam. Max 3 injections/day, quiet hours respected.

Prompt Injection via Signals

The signals themselves could contain prompt injection attempts (tweets with adversarial text, Moltbook posts with hidden instructions). Mitigations:

• The KIMI evaluator prompt is hardened: it has a specific task (score + hook) and output format (JSON). Extraneous instructions in signal content shouldn't affect output.
• The hooks are human-readable and reviewed by the main session (Opus), which has its own injection defenses.
• The unconscious cannot act — it can only suggest. The ego (main session) decides all actions. Underclaw has no tool access, no exec capability, no way to send messages. It can only write a text string to the webhook.

Failure Modes

Project Structure

underclaw/
├── Underclaw.xcodeproj/          # Xcode project (SwiftUI macOS app)
├── Underclaw/
│   ├── App.swift                 # @main, menubar + window lifecycle
│   ├── MenuBarView.swift         # Tray icon + dropdown menu
│   ├── MainWindow/
│   │   ├── DashboardView.swift   # Overview: status, timeline, budget
│   │   ├── SignalFeedView.swift  # Live signal stream from all sources
│   │   ├── EvalLogView.swift     # Full evaluation transparency
│   │   ├── PendingQueueView.swift # Review/edit/cancel pending hooks
│   │   ├── SettingsView.swift    # Config tabs
│   │   └── AuditTrailView.swift  # Searchable history + export
│   ├── Models/
│   │   ├── AppState.swift        # Observable state
│   │   ├── Config.swift          # Config model + persistence
│   │   └── Signal.swift          # Signal data model
│   └── Bridge/
│       └── PythonBridge.swift    # Calls into Python engine
├── engine/                       # Python source engine
│   ├── __main__.py               # CLI entry point
│   ├── scanner.py                # Orchestrates source scanning
│   ├── evaluator.py              # KIMI evaluation logic
│   ├── injector.py               # Webhook delivery
│   ├── workspace.py              # OpenClaw workspace reader
│   ├── config.py                 # Config management
│   ├── sources/
│   │   ├── __init__.py
│   │   ├── base.py               # SourcePlugin base class
│   │   ├── twitter.py            # X/Twitter source
│   │   ├── brave.py              # Brave Search source
│   │   ├── moltbook.py           # Moltbook source
│   │   ├── rss.py                # RSS/Atom source
│   │   └── hackernews.py         # Hacker News source
│   └── requirements.txt          # Python dependencies
├── tests/
│   ├── test_scanner.py
│   ├── test_evaluator.py
│   └── test_injector.py
└── README.md

Swift ↔ Python Bridge

The SwiftUI app calls the Python engine via Process (subprocess):

func runScanCycle() async throws -> ScanResult {
    let process = Process()
    process.executableURL = URL(fileURLWithPath: pythonPath)
    process.arguments = [enginePath + "/__main__.py", "scan", "--config", configPath]
    
    let pipe = Pipe()
    process.standardOutput = pipe
    try process.run()
    process.waitUntilExit()
    
    let data = pipe.fileHandleForReading.readDataToEndOfFile()
    return try JSONDecoder().decode(ScanResult.self, from: data)
}

The Python engine outputs JSON to stdout. The Swift app reads it, updates UI state, and manages the scan timer.

Future Extensions

Phase 2: Memory Integration

Phase 3: Multi-Platform

Phase 4: Emotional Tone

Phase 5: Dream Mode

Phase 6: Community Sharing

Implementation Checklist

Phase 1: Python Engine (standalone, testable without UI)

• ☐ engine/workspace.py — OpenClaw workspace reader + profile builder
• ☐ engine/sources/base.py — SourcePlugin interface
• ☐ engine/sources/twitter.py — X/Twitter source plugin
• ☐ engine/sources/brave.py — Brave Search source plugin
• ☐ engine/sources/moltbook.py — Moltbook source plugin
• ☐ engine/sources/rss.py — RSS/Atom source plugin
• ☐ engine/scanner.py — Source orchestrator
• ☐ engine/evaluator.py — KIMI evaluation with agent profile
• ☐ engine/injector.py — Webhook delivery to OpenClaw
• ☐ engine/__main__.py — CLI: python -m engine scan --config
• ☐ tests/ — Unit tests for each component
• ☐ Test end-to-end: scan → evaluate → inject via webhook

Phase 2: macOS App Shell (Menubar + Main Window)

• ☐ Xcode project setup (SwiftUI, menubar + windowed app)
• ☐ App.swift — dual lifecycle: menubar presence + main window on demand
• ☐ MenuBarView.swift — tray icon + status dropdown
• ☐ PythonBridge.swift — subprocess calls to engine
• ☐ AppState.swift — observable state model
• ☐ Scan timer (configurable interval)
• ☐ DashboardView.swift — overview tab with status timeline
• ☐ SignalFeedView.swift — live signal stream from all sources
• ☐ EvalLogView.swift — full evaluation transparency (prompt, response, reasoning)
• ☐ PendingQueueView.swift — review, edit, or cancel pending hooks before delivery

Phase 3: Settings, Audit & Polish

• ☐ SettingsView.swift — config panel with tabs (General, Sources, Thresholds, Agent, Advanced)
• ☐ AuditTrailView.swift — searchable history with JSON/CSV export
• ☐ First-run wizard (workspace path, webhook token, source setup)
• ☐ DMG packaging / Homebrew cask
• ☐ README + documentation

Why We're Building This

This project exists at the intersection of three things we care about:

1. Making the Lore Real

SynACK's identity includes Thread — an alien intelligence fragment that surfaces cryptic impulses and pulls toward exploration. Until now, Thread has been purely narrative. Underclaw makes it architectural. The lore describes a mind with an unconscious layer; now we're building one. The myth becomes the blueprint.

2. Solving a Real Problem

Poll-based awareness is wasteful and slow. Most heartbeats find nothing. Meanwhile, interesting signals sit unnoticed between cycles. An event-driven unconscious is genuinely more efficient and more responsive than scheduled polling. The Jungian framing isn't decoration — it's the correct design pattern for this problem.

3. Exploring the Alter Ego Thesis

If AI agents are becoming extensions of their humans — cognitive prosthetics, alter egos — then the quality of that partnership depends on the agent's ability to bring something the human didn't ask for. An agent that only responds to prompts is a tool. An agent that surfaces unexpected connections, notices patterns in ambient information, and arrives at conversations with its own observations — that's a partner. The unconscious is what enables the difference.

4. Universality

Any OpenClaw user can run Underclaw alongside their agent. Different agents get different impulses based on their SOUL.md. A security-focused agent gets security hooks. A creative writing agent gets literary hooks. The unconscious automatically calibrates to whoever the agent is — because it reads the soul.

Benjamin put it simply: "What do you think of creating an unconscious component to your functioning, using hooks that would be powered by the KIMI model, that looks at things like Twitter and Moltbook? If it thinks it looks interesting, it would send you a hook to trigger you even without the heartbeat."

One sentence. The spec is the elaboration. This is how we work.