Getting Started

New contributor guide for the Inklings codebase.

---

Prerequisites

Install all required tools before cloning.

Required Tools

Node.js >=22.0.0

node --version   # must be v22+

Install via nvm or nodejs.org.

pnpm >=10.0.0

pnpm --version   # must be v10+
npm install -g pnpm@10.30.1

Rust (latest stable)

rustc --version

Install via rustup.rs, then add required components:

rustup component add clippy rustfmt

gitleaks — required by pre-commit hook

gitleaks version
brew install gitleaks   # macOS

dprint — Markdown formatter (table alignment, line wrapping)

dprint --version
brew install dprint   # macOS

uv — Python package manager (required for apps/python-sidecar/)

uv --version
brew install uv   # macOS (or https://docs.astral.sh/uv/)

Platform Dependencies

macOS

xcode-select --install

Linux (Debian/Ubuntu)

sudo apt-get install -y libwebkit2gtk-4.1-dev \
  libappindicator3-dev librsvg2-dev patchelf libssl-dev libgtk-3-dev

---

Setup

1. Clone and install

git clone https://github.com/MasterCodeYoda/inklings.git
cd inklings
pnpm install

2. Generate types

pnpm generate:types

This runs Specta to generate TypeScript types from Rust structs into packages/contracts/generated/. Run this before dev, build, or typecheck — without it, TypeScript will not find the generated types.

3. Set up the Python sidecar (optional)

If you work on the agent harness or skill system, install the sidecar’s Python dependencies:

cd apps/python-sidecar
uv sync --group dev
cd ../..

This is only needed for sidecar development and testing. The desktop app uses a pre-built binary in production.

4. Start the app

pnpm desktop:dev

This starts Vite (React frontend) and Tauri (Rust backend) together. On first run, Cargo compiles all Rust crates — expect a few minutes.

5. Verify

cargo test          # Rust unit + integration tests
pnpm test           # All tests via Turbo (includes frontend)

All tests should pass before you start making changes.

6. Local Agent Testing (Optional)

If you work on the LLM or agent subsystems, you can run the LLM integration tests against a local Ollama installation:

# macOS
brew install ollama
ollama pull qwen3:4b   # default model for integration tests
ollama serve            # starts the server on localhost:11434

Then run the ignored tests:

cargo test -p core-tests --test llm_integration -- --ignored

Tests that cannot reach Ollama skip automatically — they never fail a clean CI run.

---

Development Environment

The app uses environment-aware paths so dev data never touches your real Inklings data:

Environment	Workspaces	Settings
Dev	{project}/.data/workspaces/	{project}/.data/settings.json
Production	~/Inklings/Workspaces/	~/Library/Application Support/Inklings/settings.json

Dev mode activates automatically for debug builds (pnpm desktop:dev). Release builds (pnpm desktop:build) use production paths.

To reset all dev app data:

./tools/dev/reset-app-data.sh          # interactive
./tools/dev/reset-app-data.sh --force  # skip confirmation

---

Key Commands

# Development
pnpm dev              # All packages via Turbo
pnpm desktop:dev      # Desktop app only (Vite + Tauri)

# Build
pnpm build            # All packages
pnpm desktop:build    # Desktop app only

# Types (run after modifying Rust structs)
pnpm generate:types

# Linting
pnpm lint             # oxlint (TypeScript)
pnpm typecheck        # TypeScript type checking
cargo clippy          # Rust linting
cargo fmt             # Rust formatting

# Testing
pnpm test                            # All tests
cargo test                           # Rust only
cargo test -p core-tests             # Real SQLite integration tests

---

Project Orientation

Architecture

Polyglot modular monolith following Clean Architecture. Dependencies flow inward — enforced at compile time via separate crates:

Framework (src-tauri)
  → Infrastructure (sqlite, import)
    → Application (use cases + service traits)
      → Domain (pure entities)

See CONTRIBUTING.md for the full directory layout and development workflow.

Key directories

Path	What lives there
crates/domain/	Pure business entities (no external deps)
crates/application/	Use cases + repository traits
crates/infrastructure/sqlite/	SQLite storage implementations
apps/desktop/src-react/	React frontend (TypeScript)
apps/desktop/src-tauri/	Tauri commands + app wiring
packages/contracts/generated/	Auto-generated Rust->TS types (do not edit)
tests/core/	Real use cases wired to real SQLite
apps/desktop/tests/	Playwright tests with mocked backend

Environment variables

If you plan to work on cloud features (auth, sync, analytics), copy the environment template:

cp .env.example .env

Edit .env with your Supabase credentials.

Further reading

• CONTRIBUTING.md — full architecture overview, build reference, and development workflow
• docs/guides/development-guide.md — vertical slicing methodology, commit discipline, testing strategy
• Domain Rules — business invariants enforced in Rust
• Systems documentation — per-system deep dives (pages, event log, import, etc.)

---

Embedding Model

On first workspace open, the app auto-downloads the embedding model (~585 MB) from HuggingFace. Download progress is streamed via Tauri events (embedding-model:download-progress). The model is SHA-256 verified before use. Semantic search is enabled by default (semantic_search_enabled setting). A dev script is also available for pre-downloading in CI or local dev:

./tools/dev/download-embedding-model.sh

---

Common Issues

Linter issues (oxlint)

The project uses oxlint for TypeScript linting. Run pnpm lint from the repo root to check for violations.

Clippy idiom errors

See docs/solutions/build-errors/rust-clippy-idioms-catalog.md for common patterns and fixes.

”Database version is newer than app version”

The workspace was created by a newer build. Update your local build or reset dev data:

./tools/dev/reset-app-data.sh --force