Synax

Turn a local codebase into a source-linked, refreshable design wiki that becomes the context layer for agent-assisted development.

English | Simplified Chinese

Supported LLM Providers

First things first: models. Synax currently exposes provider setup for OpenAI, Anthropic, DeepSeek, Google, Groq, Mistral, xAI, Perplexity, Cerebras, Cohere, DeepInfra, TogetherAI, and OpenRouter.

It also supports custom endpoints that speak one of these API formats:

• OpenAI Chat Completions compatible
• OpenAI Responses compatible
• Anthropic Messages compatible

Author note: Synax is currently developed and dogfooded mostly with DeepSeek V4. If a few paths feel especially friendly to DeepSeek users, that is not a coincidence.

Because this is 0.1.0-snapshot, provider details are still evolving. Some lower-level runtime adapters exist in code, but they should not be treated as product-ready provider support until they are wired into configuration, validation, and the UI.

Quick Start

Prerequisites

• Node.js 22 (>=22, <23).
• npm 10 or newer.
• Git.
• A native build toolchain for tree-sitter packages. On macOS, install Xcode Command Line Tools; on Windows, install Visual Studio Build Tools (C++ workload); on Linux, install build-essential (Debian/Ubuntu) or equivalent (gcc, g++, make).
• At least one LLM provider key if you want to generate wiki content or run agents.

Install

git clone https://github.com/coldmint9/Synax.git
cd Synax
npm install

Run the Web App

npm run dev

The API starts at http://localhost:3210 and the web app starts at http://localhost:5173.

Recommended first run:

1. Open http://localhost:5173.
2. Go to Settings and configure an LLM provider.
3. Import a local project directory.
4. Open the Wiki tab and generate the first Codebase Design Wiki.

Run the Desktop App

npm run dev:desktop

In development, Electron uses the local web and API servers. In packaged builds, Electron starts the bundled API sidecar.

Overview

Synax is built around one core loop: import a local codebase, analyze its files and symbols, generate a Codebase Design Wiki with source bindings, then keep that wiki refreshed as the code changes.

The Wiki is not meant to be decorative documentation. It is the project's structured context layer: a place where architecture, modules, APIs, flows, risks, decisions, source references, refresh drafts, and future agent work can meet without drifting away from the actual code.

The project is built as a TypeScript monorepo with a Hono API, React web client, libSQL/Drizzle persistence, tree-sitter based code analysis, a profile-driven agent runtime, and an Electron desktop shell.

Product Goal

Synax aims to become a local-first AI engineering workspace that turns a codebase into durable, reusable context: source-linked design documents, executable plans, agent run history, implementation evidence, and project memory.

The long-term goal is to let humans define intent and boundaries, let agents execute bounded work with clear permissions, and continuously reconcile plans, documentation, and code reality as the product evolves.

Philosophy

Synax is built around a few practical beliefs:

• The codebase is the source of truth. Documents, plans, and agent memory must point back to real files, symbols, and changes instead of floating above the work.
• Humans own intent. AI can explore, summarize, draft, and execute, but product direction, tradeoffs, and risk acceptance should remain explicit human decisions.
• Agents should be bounded collaborators, not mysterious background magic. Every useful agent run needs context, permissions, evidence, and a recoverable history.
• Documentation should stay alive. A wiki that cannot notice code drift becomes another stale artifact; Synax treats docs as something to refresh, patch, review, and trace.
• Local-first is a trust feature. Source code, credentials, runtime state, and project memory should stay under the user's control by default.
• Context is compound interest. Every run, decision, and correction should make the next run cheaper, safer, and less confused.

Version Status

Current version: 0.1.0-snapshot.

This is an early development snapshot, not a stable release. Many product details, interaction flows, runtime boundaries, and engineering hardening work are still incomplete.

Currently available or actively evolving:

• Local project import and project metadata management.
• Codebase scanning, source indexing, and Wiki generation/refresh foundations.
• LLM provider configuration and local runtime settings.
• Agent session runtime foundations, including streamed events, session state, and permission records.
• Electron desktop packaging foundations.

Known incomplete or unstable areas:

• Plan-related workflows are still experimental and not complete.
• ACP-related discovery, connection, execution, and end-to-end workflows are not complete.
• Permission approval UX, error handling, recovery flows, and safety boundaries still need refinement.
• API contracts, data schemas, prompts, and UI details may change without compatibility guarantees before a stable release.
• Tests, packaging, documentation, and production readiness still need more hardening.

Highlights

• Codebase Design Wiki: generate hierarchical documentation from source, bind wiki blocks back to files and symbols, export Markdown, and refresh docs when code changes.
• Agent Runtime: run planner, executor, reviewer, explorer, and wiki-specific profiles with streaming events, permission gates, pause, resume, cancel, and session history.
• Context Memory: persist project context, conversations, run evidence, token warnings, compression state, and searchable memory in local libSQL.
• Code Intelligence: index TypeScript, TSX, JavaScript, JSX, Python, Java, C, C++, C#, Go, Rust, PHP, Ruby, Kotlin, Swift, SQL, and shell files.
• Provider Flexibility: configure OpenAI, Anthropic, DeepSeek, Google, Groq, Mistral, xAI, Perplexity, Cerebras, Cohere, DeepInfra, TogetherAI, OpenRouter, and custom compatible API endpoints.
• Web and Desktop: use Synax as a standalone Vite web app or package it as an Electron desktop app with a bundled API sidecar.

Architecture

This diagram is the lobby map, not the full tour. For the real architecture walkthrough, install Synax, import this repository, and generate the Wiki. The project is built to explain codebases, so yes, it can explain itself. Very polite of it.😄

Configuration

Synax reads .env automatically through dotenv/config, but no template file is required. Create .env only when you need to override defaults.

Runtime data is local by default and is ignored by Git. Use a stable CONFIG_ENCRYPTION_KEY or Synax_CONFIG_SECRET before storing provider credentials you intend to keep across machines or environments.

Scripts

Project Layout

api/        Hono routes, libSQL/Drizzle schema, migrations, analyzer, wiki, context, and agent runtime
web/        React 19, Vite, HeroUI, Zustand, wiki UI, sessions UI, settings, and API clients
electron/   Desktop shell, preload bridge, menu integration, window state, and API sidecar launcher
scripts/    Development bootstrap scripts for API, web, desktop, and combined workflows
docs/       Design notes and technical plans for the Codebase Design Wiki

API Surface

The API is mounted under /api and organized by domain:

• /api/projects for project metadata and local imports.
• /api/wiki for snapshots, documents, blocks, refresh drafts, patches, exports, and design mapping.
• /api/agent-runtime for profiles, skills, contexts, sessions, streamed turns, permissions, and runtime events.
• /api/config and /api/llm for provider configuration and model discovery.
• /api/context for memory, coordinates, sessions, and contextual signals.
• /api/acp for Agent Client Protocol discovery and provider integration.
• /api/notifications, /api/logs, and /api/health for operational support.

Development Workflow

1. Keep changes focused and small enough to review.
2. Add or update tests when touching runtime behavior, persistence, route contracts, or wiki generation.
3. Run the relevant checks before opening a pull request:

npm run typecheck
npm run test
npm run lint

Packaging

Build all runtime assets and package the desktop app:

npm run build:desktop

Create distributable artifacts with Electron Forge:

npm run make:desktop

Packaged builds include server-dist, web/dist, and database migrations as Electron resources.

Contributing

Contributions should include a clear problem statement, a focused implementation, and verification notes. For larger changes, open an issue or design discussion first so the runtime, persistence, and UI impact can be reviewed before code lands.

Branch and Commit

• Branch from main with a descriptive name: feat/xxx, fix/xxx, refactor/xxx

• Use Conventional Commits:

  feat(wiki): add document export to PDF
  fix(agent-runtime): prevent duplicate tool calls in streaming
  refactor(api): simplify provider resolution logic
  

• Keep commits small and focused — one PR solves one problem.

Pull Request Checklist

1. Title under 70 characters.

2. Description includes:

   • Summary of what changed and why.
   • How to verify (test commands or manual steps).
   • Screenshots if UI changed.

3. All checks pass:

   npm run typecheck
   npm run test
   npm run lint
   

Code Style

• TypeScript strict mode; avoid any without justification.
• Backend routes in api/routes/, business logic in api/services/.
• Frontend components use HeroUI v3.
• State management with Zustand in web/src/react/state/.
• File naming: PascalCase for components, camelCase for utilities.
• No unnecessary comments — only explain the "why" when non-obvious.

Testing

• Add or update tests when touching runtime behavior, persistence, route contracts, or wiki generation.
• API tests: Vitest, __tests__/ directories or .test.ts suffix.
• Web tests: Vitest + React Testing Library (web/vitest.config.ts).

Database Changes

• Migration files go in api/db/migrations/ as raw SQL.
• Must be idempotent (CREATE TABLE IF NOT EXISTS, etc.).
• Executed sequentially on startup — no manual migration step needed.

Reporting Issues

Please include:

• Description and reproduction steps.
• Expected vs actual behavior.
• Environment info (OS, Node version, browser).
• Relevant logs or screenshots.

License

Synax is released under the MIT License.