Kazibee

An AI coding assistant that runs locally on your machine. Kazibee connects to multiple AI providers (Anthropic, OpenAI, Google, OpenRouter) and provides a persistent chat interface with deep observability into its own reasoning and tool-use traces.

Repository: demo-assistant | Product: Kazibee Stack: Electron + TypeScript, custom Wood.js bundler, better-sqlite3

Quick Start

# Install dependencies (also runs postinstall: ensures native modules)
npm install

# Start development mode
npm run dev

# Build for production
npm run build

# Package a local macOS arm64 app bundle
npm run package:mac

# Make macOS arm64 distributables (.zip/.dmg)
npm run make:mac

# Make Windows x64 distributables (.zip)
npm run make:win

# Run tests
npm run test

For full operational details, see OPERATIONS.md.

Architecture

┌─────────────┐   ┌──────────────────────────────────────────┐
│   Electron  │   │              Main Process                 │
│   Renderer │   │  app.ts  ·  services/  ·  db/              │
│  (ui/)      │   │  controller/  ·  repositories/            │
└─────────────┘   └──────────────────────────────────────────┘
                                          │
                          ┌───────────────┼────────────────────┐
                          ▼               ▼                    ▼
                       main.db     threads/thread-*.db  trace/telemetry.db
                     (app-wide)    (transcript + state)   (traces + metrics)

Key directories

| Path | Purpose | |------|---------| | server/services/ | Core application logic (chat pipeline, tool registry, provider routing) | | server/controller/ | IPC request handlers — thin bridges between renderer and services | | server/db/ | SQLite schemas and migrations | | server/repositories/ | Data access layer for conversations, threads, replay events | | ui/providers/ | Frontend state management (React context) | | ui/services/ | Frontend IPC client wrappers | | shared/chat_runtime/ | Types and schemas shared between main and renderer | | specs/ | Feature specs following a lifecycle: draft → review → approved → implemented |

Key Rules

Use Logger, not console.log

All logging goes through the injected Logger instance:

import { Logger } from '@noego/logger';
const log = new Logger('MyService');

log.info('starting operation', { traceId });
log.error('operation failed', { error, traceId });

Direct console.log / console.error calls will fail the lint check.

Emit trace events for all async pipelines

Every service that handles an async operation must emit structured trace events:

await Logger.trace('chat.pipeline.run', {
  conversationId,
  provider: 'anthropic',
  inputTokens,
  outputTokens,
  durationMs,
});

This feeds the trace database and powers the debugging tools. For trace-driven behavior checks, Reactive Trace lets traces react to other traces and emit trace.anomaly.violation when temporal/keyed rules break; see @noego/trace Reactive Trace docs. See OPERATIONS.md §Trace Events for the full event catalog.

Debugging Sequence

When something goes wrong, follow this order:

1. logs/app.log — Application-level logs (start here)
2. Framework trace DB — @noego/trace SQLite at the path configured in wood.config.yml (see OPERATIONS.md for SQL query patterns)
3. Canonical thread DB — <dataRoot>/<threads.db_path> for persisted messages and compact conversation_event_sequence / conversation_tool_calls state; use telemetry for ordered event history
4. Cross-device trace server — Remote server at the IP in wood.config.yml if the issue originated on another machine

Where to Find Things

| Looking for | Go to | |------------|-------| | How imports are enforced | npm run check:imports, npm run migrate:imports:named | | Development setup details | scripts/dev.sh, scripts/ensure-native.sh | | Worktree workflow | OPERATIONS.md §Worktrees | | Testing strategy | OPERATIONS.md §Tests | | Design patterns | specs/implemented/project-patterns.md | | Embedded browser previews | server/browser/ | | OpenAPI/RPC schemas | server/stitch.yaml, ui/stitch.yaml | | Known issues | issues/ | | Experiments | experiments/ |

Start Here For…

| Goal | Reference | |------|-----------| | I want to run the app | Quick Start above, then OPERATIONS.md §Dev Setup | | I want to understand the codebase | OPERATIONS.md §Architecture | | I want to add a new AI provider | OPERATIONS.md §AI Provider Abstraction | | I want to add a new tool | OPERATIONS.md §Tool System | | I want to understand how chat works | OPERATIONS.md §Chat Pipeline | | I want to trace an async operation | OPERATIONS.md §Trace Events | | I want to write a feature spec | specs/README.md | | I'm an AI agent | AGENTS.md (→ CLAUDE.md) |