Development setup

Cognis is a Cargo workspace. If you’ve worked in Rust before, this should feel familiar. If not, the steps below are everything you need.

Prerequisites

Rust 1.75 or newer. Install via rustup.
A Unix-like shell. Most commands assume bash/zsh; PowerShell works for the cargo bits.
Optional: cargo-watch for cargo watch -x test during iteration.
Optional: cargo-expand when working on macros.

Clone and build

git clone https://github.com/0xvasanth/cognis.git
cd cognis

cargo build --workspace
cargo test --workspace

The first build takes a few minutes — reqwest, sqlx, and tokio aren’t small. Subsequent builds are incremental.

Build with all providers

Most provider-specific code is feature-gated. To compile everything:

cargo build -p cognis --features all-providers
cargo build -p cognis-trace --features langfuse
cargo build -p cognis-graph --features sqlite,postgres
cargo build -p cognis-rag --features all-loaders,all-vectorstores

CI builds a matrix of feature combinations; matching that locally before pushing saves cycles.

Run a single test

cargo test -p cognis-core
cargo test -p cognis --lib agent::memory          # one module
cargo test -p cognis-graph test_resume_after_interrupt   # one test by name

Run an example

Examples live in examples/ and are registered in crates/examples/Cargo.toml. Run by registered name:

cargo run -p cognis-examples --example chains_pipe_operator

# Provider-backed:
COGNIS_PROVIDER=ollama COGNIS_OLLAMA_MODEL=llama3.1 \
  cargo run -p cognis-examples --example agents_react_agent

See Examples for the full list.

Worktrees

For non-trivial changes (multi-day work, parallel branches), a worktree gives you an isolated checkout without leaving your primary tree:

git worktree add .worktrees/my-feature -b feature/my-feature
cd .worktrees/my-feature
# work here…
git worktree remove .worktrees/my-feature

The .worktrees/ directory is project-local and globally gitignored.

Pre-push checklist

Before opening a PR, run these in order. They match what CI runs:

# 1. Format.
cargo fmt --all

# 2. Clippy with all features (matches CI).
cargo clippy --workspace --features all-providers -- -D warnings

# 3. Tests across the workspace.
cargo test --workspace

If you have access to Cubic, also run a code review pass:

cubic review

Fix any issues Cubic flags before pushing.

Working on docs

The docs site lives under docs/mintlify/ and is built with Mintlify. Preview locally if you have the Mintlify CLI:

cd docs/mintlify
mintlify dev

Otherwise, write Markdown and check it in mintlify’s preview environment when you open the PR.

Working on macros

Macros live in crates/cognis-macros. To inspect what a derive expands to:

cargo install cargo-expand
cargo expand -p cognis --tests

Output should be readable Rust. Macros that produce unreadable code are a smell — keep generated code transparent.

Clean rebuild

If the build gets confused after large dependency churn:

cargo clean
cargo build --workspace

cargo clean is heavy; reach for it after upgrading Rust or changing many features at once, not as a daily habit.

Architecture

Crate boundaries and design rules.

PR guidelines

What to include in your PR description.

Adding a provider

Step-by-step for a new LLM client.

Contribute

Development setup

Prerequisites

Clone and build

Build with all providers

Run a single test

Run an example

Worktrees

Pre-push checklist

Working on docs

Working on macros

Clean rebuild

See also

Architecture

PR guidelines

Adding a provider

​Prerequisites

​Clone and build

​Build with all providers

​Run a single test

​Run an example

​Worktrees

​Pre-push checklist

​Working on docs

​Working on macros

​Clean rebuild

​See also

Architecture

PR guidelines

Adding a provider

Prerequisites

Clone and build

Build with all providers

Run a single test

Run an example

Worktrees

Pre-push checklist

Working on docs

Working on macros

Clean rebuild

See also