Local Development Guide
Relevant source files
The following files were used as context for generating this wiki page:
The Cogmo Local Development Guide provides the necessary technical information for developers to set up, run, and test the Cogmo agent runtime in a local environment. Cogmo is a modular system built with TypeScript on Node.js, designed for a single technical user to run on self-controlled infrastructure.
Local development leverages testcontainers to manage infrastructure dependencies such as PostgreSQL, Redis, Inngest, and Hindsight, ensuring a consistent environment that mirrors production configurations.
Sources: CLAUDE.md:1-10, README.md:13-20, README.md:95-101
Development Environment Setup
Infrastructure Dependencies
Cogmo requires several core infrastructure components to function. For local development, these are typically managed via testcontainers or started manually using development scripts.
| Component | Purpose | Requirement |
|---|---|---|
| Node.js | Primary runtime | v24 recommended |
| pnpm | Package management | Latest |
| PostgreSQL | Persistent storage | v18 (recommended) with pgvector |
| Redis | Event queue / state | v7+ |
| Inngest | Orchestration | Dev server or production deployment |
| Hindsight | Vector memory | HTTP API on port 8888 |
Sources: README.md:31-40, DEPLOYMENT.md:5-15, CLAUDE.md:78-85
Local Workflow Commands
The project uses pnpm for task execution. The following commands are essential for the local development cycle:
# Start infrastructure and the application
pnpm dev:infra
# Open an interactive console for direct channel communication
pnpm console
# Standard pre-push check
pnpm typecheck && pnpm lint && pnpm test
# Record new LLM fixtures and run integration tests
pnpm test:record
pnpm test:integration
Sources: CONTRIBUTING.md:15-25, design/testing.md:3-8
System Configuration and Setup
Setup Wizard
Cogmo includes an interactive TUI setup wizard (cogmo setup) built with @clack/prompts. This wizard is idempotent and re-runnable, allowing developers to configure providers and credentials without manual environment variable manipulation.
The wizard validates credentials live against providers (e.g., calling getMe for Telegram or listing models for Anthropic) before encrypting them into the database.
Sources: src/setup/wizard.ts:13-30, src/setup/wizard.ts:890-950, README.md:55-75
Secret Management
Secrets are never written to disk or logged. They are encrypted using AES-256-GCM with a key derived via HKDF from the COGMO_MASTER_KEY. These encrypted secrets are stored in the secrets table.
Sources: README.md:76-80, DEPLOYMENT.md:65-70
Testing Strategy
Cogmo employs a three-tier testing structure to ensure system reliability, ranging from unit tests to full end-to-end smoke tests.
Testing Tiers
| Tier | Focus | Infrastructure |
|---|---|---|
| Unit Tests | Deterministic logic | PGlite (WASM PG17), Vitest |
| Integration Tests | Orchestration & Event Flow | Testcontainers (PG, Redis, Inngest) |
| E2E Tests | Full deployment stack | Cogmo subprocess + Testcontainers |
Sources: design/testing.md:10-15, design/testing.md:23-28, design/testing.md:43-48
LLM Mocking with llmock
To handle non-deterministic LLM responses during tests, Cogmo uses @copilotkit/llmock. This allows for recording real LLM interactions as fixtures and replaying them during CI/CD to ensure consistent test results.
Module Structure and Code Style
Developers must adhere to the modular boundaries defined in the architecture to maintain system evolution and testability.
Module Map
| Module | Responsibility |
|---|---|
src/agent/ | Domain logic, tools, agentic loop, prompt assembly. |
src/transport/ | Channel adapters (Telegram, Direct), session management. |
src/llm/ | Provider abstraction (Anthropic, OpenAI-compatible). |
src/memory/ | Hindsight adapter and memory provider interface. |
src/inngest/ | Infrastructure setup and event definitions. |
Sources: CLAUDE.md:102-120
Coding Standards
- Named Exports: Use
functiondeclarations for named exports. - Strict Encapsulation: Use
#privatefields for internal state. - Dependency Injection: Prefer DI over hard imports to facilitate mocking.
- Result Pattern: Use
Result<T, E>at boundaries rather than throwing errors. - Commits: Follow Conventional Commits (e.g.,
feat(agent): description).
Sources: CLAUDE.md:122-130, CONTRIBUTING.md:45-60
Conclusion
Setting up a local development environment for Cogmo involves establishing the necessary infrastructure via testcontainers and using the interactive setup wizard to configure the agent. By adhering to the three-tier testing strategy and following the modular architecture rules, developers can contribute to the system's self-evolution while maintaining high code quality and reliability.
Sources: README.md:95-105, design/testing.md:1-5