Skip to main content

​
Clone the Repository

The fastest way to get started: 
git clone https://github.com/clarkOS/clark my-agent
cd my-agent/example/convex
npm install
This gives you a complete project with:
  • Convex backend schema and functions
  • TypeScript source code
  • Terminal UI (React Ink)
  • 179 passing tests
  • Environment template

​
Quick Validation

Run the doctor script to check your setup: 
npm run doctor
This validates Node version, dependencies, and environment configuration.

​
Try Demo Mode

No API keys? No problem. Run with an in-memory backend: 
npm run demo
This starts the terminal UI with sample data, letting you explore the framework before configuring external services.

​
Environment Variables

Copy the template: 
cp .env.example .env.local
Edit .env.local: 
# Required for full mode
CONVEX_URL=https://your-project.convex.cloud
OPENROUTER_KEY=your-openrouter-api-key
GEMINI_API_KEY=your-gemini-key

# Optional - auth tokens
TICK_TOKEN=secure-random-token
WRITE_TOKEN=secure-random-token

​
Getting API Keys

ServicePurposeURL
ConvexBackendRun npx convex dev and copy deployment URL
OpenRouterLLMopenrouter.ai
GeminiEmbeddings (free)aistudio.google.com

​
Project Structure

clark/
├── README.md
├── docs/                    # Audit documentation
├── scripts/
│   └── doctor.js            # Preflight validation
└── example/
    └── convex/              # Reference implementation
        ├── .env.example     # Environment template
        ├── package.json
        ├── convex/          # Convex backend
        │   ├── schema.ts    # Database schema
        │   ├── http.ts      # HTTP endpoints
        │   ├── state.ts     # State queries/mutations
        │   ├── memories.ts  # Memory operations
        │   ├── knowledge.ts # Knowledge operations
        │   └── logs.ts      # Logging
        ├── src/
        │   ├── cli.tsx      # CLI entry point
        │   ├── core/        # Agent runtime, tick system
        │   ├── memory/      # Memory store, deduplication
        │   ├── knowledge/   # Knowledge base
        │   ├── plugins/     # Plugin system
        │   ├── llm/         # LLM & embedding clients
        │   ├── services/    # Background services
        │   ├── templates/   # Prompt templates
        │   └── ui/          # Terminal UI (Ink + React)
        └── tests/           # Jest tests (179 total)

​
Verify Installation

Start the development server: 
npm run dev
You should see the terminal UI with the agent status.

​
Check API Endpoints

If using the Convex backend: 
# Health check
curl http://localhost:3001/health

# Expected response:
# {"ok":true,"service":"clark-agent","now":...,"lastTick":...}

# Agent state
curl http://localhost:3001/state

​
Run Tests

Validate everything works: 
npm test
All 179 tests should pass.

​
Set Up Your Own Convex Project

To use your own Convex deployment: 
# Install Convex CLI
npm install -g convex

# Initialize new project
npx convex init

# Start dev server
npx convex dev
Then update CONVEX_URL in .env.local with your new deployment URL.

​
Next Steps

Quickstart

Build your first agent

Core Concepts

Understand the architecture