Quickstart

Prerequisites

Before you begin, make sure you have:

Node.js 18+ installed
npm package manager
An OpenRouter API key (optional - demo mode works without keys)

Don’t have an OpenRouter key? Try demo mode first - it runs with an in-memory backend and sample data, no API keys required.

Create Your Agent

Clone the repository

Clone the ClarkOS SDK:

git clone https://github.com/clarkOS/clark my-agent
cd my-agent/example/convex

This gives you a fully-configured project with:

Convex backend setup
TypeScript configuration
Terminal UI (React Ink)
179 passing tests

Install dependencies

Install the required packages:

npm install

Run the doctor (optional)

Validate your environment:

npm run doctor

This checks Node version, environment variables, and dependencies.

Try demo mode (no keys needed)

Start the agent with an in-memory backend:

npm run demo

This runs the terminal UI with sample data. Great for exploring before configuring API keys.

Or configure for full mode

Set up your environment variables:

cp .env.example .env.local

Edit .env.local with your API keys:

CONVEX_URL=https://your-project.convex.cloud
OPENROUTER_KEY=your-openrouter-key
GEMINI_API_KEY=your-gemini-key

Then run:

npm run dev

Terminal UI

The SDK includes a terminal-based interface built with React Ink:

┌─────────────────────────────────────────────┐
│  CLARK - Autonomous Agent                    │
│  Mood: curious | Health: 78 | Routine: day  │
├─────────────────────────────────────────────┤
│      ╭──────────╮                           │
│      │  ◉    ◉  │                           │
│      │    ──    │                           │
│      ╰──────────╯                           │
└─────────────────────────────────────────────┘

Keyboard Controls

Key	Action
`q`	Quit
`r`	Refresh data
`m`	Toggle radio panel
`v`	Toggle view mode
`Ctrl+C`	Force quit

Your First Tick

The tick is the heartbeat of your agent. Every tick, your agent:

Loads its current state and memories
Gathers context (knowledge, recent activity)
Calculates routine from current time
Executes plugin hooks
Updates state (health drift, counters)

To trigger a tick programmatically:

import { Agent, ConvexBackend } from './src';

const agent = new Agent({
  backend: new ConvexBackend({ url: process.env.CONVEX_URL! }),
});

await agent.tick();

Explore the API

Your agent exposes HTTP endpoints via the Convex backend:

Endpoint	Method	Description
`/health`	GET	Health check
`/state`	GET	Current agent state
`/memories`	GET	Query memories
`/memories`	POST	Store a memory
`/memories/core`	GET	Core memories
`/memories/stats`	GET	Memory statistics
`/knowledge`	GET	Knowledge items
`/logs`	GET	Activity logs

Add a Plugin

Extend your agent with a plugin:

// plugins/logger.ts
import type { Plugin } from "./src/plugins";

export const loggerPlugin: Plugin = {
  name: "logger",
  version: "1.0.0",
  description: "Logs tick activity",

  init(agent) {
    console.log("Logger plugin initialized");
  },

  onTick(context) {
    console.log(`Tick executed. Mood: ${context.state.mood}, Health: ${context.state.health}`);
    console.log(`Memories loaded: ${context.memories.length}`);
  }
};

import { Agent } from "./src";
import { ConvexBackend } from "./src/backend";
import { loggerPlugin } from "./plugins/logger";

const agent = new Agent({
  backend: new ConvexBackend({ url: process.env.CONVEX_URL! }),
  plugins: [loggerPlugin]
});

await agent.tick();

Run the Tests

The SDK includes 179 tests:

npm test

Next Steps

Understand Agents

Learn the core agent architecture.

Master Memory

Deep dive into the memory system.

Build Plugins

Create custom agent capabilities.

Explore Examples

See complete agent implementations.

Need help? Open an issue on GitHub.

Getting Started

Core Concepts

Guides

Plugins

Prerequisites

Create Your Agent

Terminal UI

Keyboard Controls

Your First Tick

Explore the API

Add a Plugin

Run the Tests

Next Steps

Understand Agents

Master Memory

Build Plugins

Explore Examples

​Prerequisites

​Create Your Agent

​Terminal UI

​Keyboard Controls

​Your First Tick

​Explore the API

​Add a Plugin

​Run the Tests

​Next Steps

Understand Agents

Master Memory

Build Plugins

Explore Examples

Prerequisites

Create Your Agent

Terminal UI

Keyboard Controls

Your First Tick

Explore the API

Add a Plugin

Run the Tests

Next Steps