agentic

agentic is a Node.js + PNPM/Turborepo monorepo. The local coding-agent terminal host is geek, implemented with OpenTUI React. The Web Chatbot server is a Node HTTP service with /api/actions and /api/stream, and it serves the built Web Chat frontend from web/dist.

Quick Start

fnm use
pnpm install
pnpm build
pnpm test

Run The Server

pnpm server

The Node server exposes:

• GET /health
• POST /api/actions
• GET /api/stream?conversation_id=...
• built Web Chat static assets from web/dist after pnpm --filter web build

Basic action envelope:

{
  "action": "send_message",
  "request_id": "req_1",
  "body": {
    "content": "hello"
  }
}

The first send_message without conversation_id creates a conversation, persists the user message, starts one run for that conversation, and streams events over SSE. The runtime uses the configured OpenAI-compatible provider; set DEEPSEEK_API_KEY or AGENTIC_WEB_API_KEY before expecting a real model response. Echo output is available only when a provider model is explicitly set to echo.

Run Web Chat

Start the Node server and the Vite frontend in separate terminals:

pnpm server
pnpm --filter web dev

The frontend lives under web/ and talks to the Node server through the Vite proxy for /api/actions, /api/stream, and /health. It is now the Web Chatbot v1 baseline rather than the old coding-agent WebSocket client.

For a single-process production-style smoke, build the frontend first and then run the Node server:

pnpm --filter web build
pnpm server

The server serves web/dist by default. Set AGENTIC_WEB_DIST to serve a different built asset directory.

Run Geek

pnpm geek

OpenTUI's real CLI renderer requires native FFI support. Default Geek tests run non-native view-model checks:

pnpm --filter @agentic/geek test

The native OpenTUI frame gate runs through Node 26.3+ with native FFI enabled:

pnpm --filter @agentic/geek test:opentui

Use the repository .node-version (26.3.1) or another Node runtime that supports node --experimental-ffi.

Plain smoke rendering:

pnpm --filter @agentic/geek dev -- --plain --eval hello

The Node local runtime currently supports slash-driven file/bash_task/create_task tools, approval pause/resume, structured user questions, and load_skill over the Node filesystem skill catalog. It also has a baseline model-driven tool-call loop that sends tool specs to the model, executes requested tools, and feeds tool results into the next turn. Subagents now have a Node baseline with filesystem catalog discovery, child sessions, parent subagent_start/ subagent_end events, and tool whitelist enforcement. Tool argument decoding includes focused JSON repair for common LLM mistakes.

Monorepo Layout

apps/
  geek/       # OpenTUI React terminal host
  server/     # Node HTTP action + SSE Web Chatbot server
packages/
  core/       # shared DTOs, config, model adapters, runtimes, storage
web/          # React/Vite Web Chatbot frontend
docs/         # architecture and migration documentation

Root scripts delegate to Turborepo:

pnpm build
pnpm check
pnpm test
pnpm dev

Configuration

Geek reads JSON5/JSONC config from ~/.config/geek/config.json5; if it does not exist, a default file is created. Geek supports multiple named providers in that config and selects one through defaultProvider and defaultModel. Geek local session data is stored under $HOME/.local/share/geek. A full example is checked in at apps/geek/config.example.json5.

DeepSeek example:

{
  defaultProvider: "deepseek",
  defaultModel: "deepseek-chat",
  providers: {
    deepseek: {
      apiKey: "${DEEPSEEK_API_KEY}",
      baseUrl: "https://api.deepseek.com",
      models: {
        "deepseek-chat": {
          name: "deepseek-chat",
          temperature: 0.1,
        },
      },
    },
  },
}

Geek also reads ~/.config/geek/auth.json unless AGENTIC_AUTH is set:

{
  "deepseek": "sk-..."
}

That auth entry is exposed to config resolution as DEEPSEEK_API_KEY. Values from auth.json override real environment variables with the same name.

Provider variables:

Variable	Meaning
AGENTIC_AUTH	optional Geek auth JSON file path
DEEPSEEK_API_KEY	optional key referenced by the generated Geek config template
DEEPSEEK_BASE_URL	Web Chat fallback OpenAI-compatible base URL
DEEPSEEK_MODEL	Web Chat fallback model
AGENTIC_WEB_API_KEY	Web Chat provider key
AGENTIC_WEB_BASE_URL	Web Chat provider base URL
AGENTIC_WEB_MODEL	Web Chat provider model
AGENTIC_WEB_SYSTEM_PROMPT	Web Chat global system prompt
AGENTIC_DATA_DIR	server data directory for SQLite
AGENTIC_WEB_DIST	optional built Web Chat static asset directory

Verification

Current verification path:

1. pnpm install
2. pnpm check
3. pnpm test
4. pnpm --filter @agentic/server test
5. pnpm --filter @agentic/geek test
6. pnpm --filter @agentic/geek test:opentui
7. pnpm --filter web build
8. pnpm build

Default Geek tests cover non-native view-model behavior. The opt-in test:opentui command is the Node FFI native OpenTUI frame gate. The server tests exercise /health and the send_message action against the real Node HTTP server.