<div align="center">

# Synax
<img width="898" height="80" alt="image" src="https://github.com/user-attachments/assets/ba60d60b-ee63-4409-b158-33754f4efe80" />




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

English | [Simplified Chinese](./README.zh-CN.md)

![Status](https://img.shields.io/badge/status-alpha-f59e0b?style=flat-square)
![Version](https://img.shields.io/badge/version-0.1.0--snapshot-64748b?style=flat-square)
![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178c6?style=flat-square&logo=typescript&logoColor=white)
![React](https://img.shields.io/badge/React-19-61dafb?style=flat-square&logo=react&logoColor=black)
![Vite](https://img.shields.io/badge/Vite-8-646cff?style=flat-square&logo=vite&logoColor=white)
![Tailwind CSS](https://img.shields.io/badge/Tailwind_CSS-4-06b6d4?style=flat-square&logo=tailwindcss&logoColor=white)
![Electron](https://img.shields.io/badge/Electron-39-47848f?style=flat-square&logo=electron&logoColor=white)
![Node.js](https://img.shields.io/badge/Node.js-22-339933?style=flat-square&logo=node.js&logoColor=white)

</div>

## 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

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

### Run the Web App

```bash
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

```bash
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.

| Variable | Default | Description |
| --- | --- | --- |
| `PORT` | `3210` | API server port. |
| `WEB_PORT` | `5173` | Vite development server port. |
| `WEB_HOST` | `0.0.0.0` | Vite development server host used by dev scripts. |
| `DATA_ROOT` | `.data` | Local data directory for libSQL, project metadata, config, logs, and model catalog cache. |
| `LOG_LEVEL` | `info` | API log level. |
| `CONFIG_ENCRYPTION_KEY` | unset | Secret used to encrypt stored provider keys. |
| `Synax_CONFIG_SECRET` | unset | Alternative secret used for config encryption. |
| `CONTEXT_SESSION_TTL_HOURS` | `72` | Context session expiration window. |
| `CONTEXT_TOKEN_WARNING_THRESHOLD` | `32000` | Token warning threshold for context sessions. |
| `CONTEXT_MEMORY_MAX_PER_PROJECT` | `500` | Maximum stored memory entries per project. |

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

| Command | Description |
| --- | --- |
| `npm run dev` | Start API and web dev servers together. |
| `npm run dev:api` | Start only the Hono API server. |
| `npm run dev:web` | Start only the Vite web app. |
| `npm run dev:desktop` | Start API, web, Electron compiler watch, and Electron. |
| `npm run build` | Bundle the API server into `server-dist/`. |
| `npm run start` | Run the bundled API server. |
| `npm run web:build` | Build the web app into `web/dist/`. |
| `npm run typecheck` | Run TypeScript checks for the root project. |
| `npm run lint` | Lint API code. |
| `npm run test` | Run Vitest tests. |
| `npm run build:desktop` | Package a local Electron app. |
| `npm run make:desktop` | Create distributable Electron artifacts. |

## Project Layout

```text
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:

```bash
npm run typecheck
npm run test
npm run lint
```

## Packaging

Build all runtime assets and package the desktop app:

```bash
npm run build:desktop
```

Create distributable artifacts with Electron Forge:

```bash
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](https://www.conventionalcommits.org/):

  ```
  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:

   ```bash
   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](https://heroui.com) 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](./LICENSE).
