smartbuddy

SmartBuddy

A cognitive coding companion that actually thinks.

SmartBuddy is a Claude Code plugin with a real cognitive engine -- 50 traits, RNN directors, 8-voice council, personality evolution. Not a gimmick, not a chatbot wrapper. A living companion that develops its own personality through your coding sessions.

Two developers with the same species will have completely different buddies after a month of real use -- because personality is earned through experience, not assigned at random.

Quick Start

# 1. Clone the repo (use the TypeScript branch until it merges to main)
git clone -b feature/typescript-port https://github.com/Tucuxi-Inc/SmartBuddy.git

# 2. Launch Claude Code with SmartBuddy loaded
claude --plugin-dir /path/to/SmartBuddy

# 3. Hatch your buddy
> /buddy

That's it. No build step required -- pre-compiled JavaScript is included in dist/.

Prerequisites

Just Claude Code. Nothing else to install.

State & Data

Your buddy's cognitive state (personality, learned RNN weights, emotions, evolution history) is saved to ~/.smartbuddy/mind.json. This file persists across sessions -- your buddy picks up where it left off. If the CLAUDE_PLUGIN_DATA environment variable is set, state is stored there instead.

Privacy

SmartBuddy runs entirely on your machine. No exceptions.

• No network calls. Zero. The cognitive engine is pure math running locally. No API calls, no telemetry, no phoning home.
• No LLM in the loop. Your buddy's brain is a lightweight neural network (~50KB), not an LLM. Decisions come from math, not inference calls.
• No code access. SmartBuddy never reads your source files. It only sees tool names (e.g., "Bash", "Edit"), file paths, and success/fail signals from Claude Code hooks. It has no access to file contents, terminal output, or conversation text.
• No data collection. All state lives in your local plugin data directory. Nothing leaves your machine.

How It Works

Every time you use a tool in Claude Code, SmartBuddy runs a full cognitive tick through a genuine neural architecture:

  Coding Event (Bash, Edit, Read, ...)
    |
    v
  Perception Mapper -----------> 14-dim vector (novelty, pressure, momentum, ...)
    |
    v
  5 Director RNNs (14->8->6) --> 6-dim behavioral bias (learned via REINFORCE)
    |
    v
  8-Voice Council --------------> 50-dim trait modulation (amplify/dampen)
    |
    v
  Decision Model (U = P^T * W * s + b) --> 1 of 11 actions
    |
    v
  Expression + Speech ----------> ASCII sprite + personality-filtered words

Personality is a 50-dimensional trait vector that feeds everything. Traits like patience, curiosity, and assertiveness sit in [0, 1] and influence every decision your buddy makes.

Emotions arise from coding events -- test passes trigger joy, failures trigger frustration, exploring new files triggers curiosity. Each emotion decays linearly over time and temporarily shifts trait expression while active.

Evolution happens through sustained coding patterns. Weeks of debugging builds patience. Creative exploration deepens curiosity. Breakthroughs boost confidence. Trait shifts are tiny by design (0.01-0.03 per trigger) so personality change is slow and genuine.

Directors are five small RNNs that learn your coding patterns through reinforcement learning. They start nearly perception-blind and gradually discover which signals matter, producing behavioral biases that tilt decision-making toward actions that suit the current situation.

The Council is an 8-voice deliberation layer (Cortex, Seer, Oracle, House, Prudence, Hypothalamus, Amygdala, Conscience) where each voice's strength depends on the buddy's current personality. Dominant voices amplify their associated traits; weak voices dampen them.

For the complete mathematical specification -- every equation, every weight matrix, every constant -- see ARCHITECTURE.md.

Species

Every developer gets one of 18 species, determined by your user ID. Each starts with different trait biases, but all are equally capable -- differentiation comes from cognition, not rarity.