8000 GitHub - coldmint9/Synax: A local workspace for coding agents and codebase documentation. · GitHub
[go: up one dir, main page]

Skip to content
coldmint9Public

About

A local workspace for coding agents and codebase documentation.

Topics

Resources

Stars

14 stars

Watchers

0 watching

Forks

Latest commit

 

History

818 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Synax

A local workspace for coding agents and codebase documentation.

English | 简体中文

Synax brings agent conversations, source files, diffs, and a terminal into one app. Import a local project to start working with an agent, inspect source files, review changes, and verify them in the terminal.

The project is in alpha.

Sessions use the native Synax engine. ACP and external agent CLI/SDK execution adapters have been removed. Existing histories remain readable and can be archived; start a new Synax session for further work. Model APIs, MCP and computer-use tools remain available through the native engine.

When the execution directory contains pom.xml, or an ancestor within the same Git repository does, the system prompt includes Maven build guidance: prefer the Maven Wrapper, verify affected modules incrementally, avoid unnecessary clean, enable parallel builds only with compatible plugins, and report skipped tests. Other projects receive no Maven guidance.

file.generate lets agents use Python templates, loops and text transformations for multi-file scaffolds, batch rewrites, and long or escape-sensitive content. Use file.patch for small edits and file.write for short complete files. Scripts stage changes through synax.write/delete/move; the runtime validates permissions, paths, read freshness and write scopes before committing under a workspace lock. Failed commits roll back, with any incomplete restoration reported explicitly. Deleting or moving still requires the file.delete capability.

Desktop installers bundle a pinned Python runtime; users do not need to install Python separately. The estimated installer increase is 30–45 MB, subject to platform build measurements. Development can use python3 on PATH, or an interpreter selected with SYNAX_PYTHON_RUNTIME. The tool is hidden when no runtime is available. Limits are 120 files, 64 MiB total and 8 MiB per UTF-8 text file. Ordinary open()/pathlib access is read-only within the workspace; networking and subprocesses are blocked. Approval shows the script, while the final file list arrives after execution. Python audit hooks are guardrails against mistakes, not a hardened sandbox for hostile code.

Quick Start

1. Requirements

Install Node.js 22 (>=22 <23), npm 10 or later, and Git. Native dependencies also need Python 3 and a C/C++ build toolchain:

System Build tools
macOS Xcode Command Line Tools (xcode-select --install)
Windows Visual Studio 2022 Build Tools with the Desktop development with C++ workload
Linux GCC, G++, and Make; on Debian/Ubuntu, install build-essential

2. Install dependencies

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

3. Start the app

The entry points below can be started as needed. Development commands use isolated profiles by default, so the production desktop app, Web development build, and Electron development build do not share runtime data.

Web (browser)

One command starts both the API and the frontend:

npm run dev:all

npm run dev is an alias for the same script. The Web development profile uses the API on 3211, the web development server on 5174, and the data root ~/.synax/web-dev; then open localhost:5174.

Production builds

Build the runtime and frontend:

npm run build
npm run client:build

The build outputs are server-dist/ and client/dist/. Use npm run dev:all for the browser workflow, or npm run build:desktop to package the desktop application.

Local storage

Synax 2.0 uses RocksDB in the Rust Runtime Sidecar for session state, history, context memory, skill and extension state, tool grants, media jobs, terminals, and process leases. Configuration, project registration, and logs use JSON/files. The project no longer creates or reads SQLite databases. Set DATA_ROOT to change the runtime root; the default is ~/.synax.

Desktop (Electron)

npm run dev:desktop

This compiles the Electron TypeScript sources, starts the API and web servers, waits for both to be ready, and then launches Electron with hot reload (electronmon). A desktop window opens automatically; no browser is needed.

The installed production desktop app continues to use ~/.synax, while the Web development profile uses ~/.synax/web-dev, so the two runtimes do not share the database, sessions, runtime token, or project index. If you also run the Electron development build, npm run dev:desktop automatically uses ~/.synax/desktop-dev, keeps Vite on 5173, and lets the Sidecar API use an OS-assigned port. DATA_ROOT, PORT, and WEB_PORT can be used to override the active profile defaults.

To produce an installable desktop build instead of running it in development mode:

npm run make:desktop

Artifacts are written to out/make/. Build on the target operating system and CPU architecture — libSQL and node-pty ship native binaries. Packaged apps include their own runtime, so end users do not need a separate Node.js installation.

Full desktop updates use electron-updater for feeds and verified downloads: macOS consumes an app ZIP, and Windows consumes the installer ending in -NSIS.exe. Developer ID signed macOS apps use the native framework installer. Ad-hoc, unsigned and self-signed apps use Synax's bundle replacement helper: it checks the archive, version and architecture, stages the new app, waits for exit, replaces and relaunches it, and retains the previous bundle until the new app reports healthy. Self-signed apps must retain the same signing identity. Downloads and restarts require confirmation. Older macOS releases that only use the native updater may require one manual installation to enable this path. On Windows, make:desktop also generates the NSIS installer; existing Squirrel or portable installations need one manual NSIS installation. Preserve ~/.synax and the user profile during migration. Legacy Squirrel packages, DMGs and update manifests remain published, and compatible UI updates retain their separate workflow.

Without SYNAX_MAC_SIGN_IDENTITY, macOS builds use free ad-hoc signing, including stable tags; no certificate or paid Apple account is needed for the compatibility updater. Ad-hoc signing checks integrity but does not establish publisher identity: release authenticity relies on the HTTPS release source, and first installation remains subject to Gatekeeper approval. Synax does not disable system security settings. For Developer ID signing, configure SYNAX_MAC_SIGN_IDENTITY and an imported certificate; CI imports SYNAX_MAC_CERTIFICATE (base64 P12) with SYNAX_MAC_CERTIFICATE_PASSWORD. Notarization additionally uses SYNAX_APPLE_ID, SYNAX_APPLE_APP_PASSWORD and SYNAX_APPLE_TEAM_ID. Windows builds generate a ten-year self-signed code-signing certificate locally when no CSC_LINK/CSC_KEY_PASSWORD pair is supplied. For stable CI releases, preserve that same PFX by storing its base64 contents, password, and publisher in SYNAX_WINDOWS_CSC_LINK, SYNAX_WINDOWS_CSC_KEY_PASSWORD, and SYNAX_WINDOWS_PUBLISHER; the NSIS installer adds the public certificate to the current user's Trusted Publishers store before the app starts. This lets electron-updater verify the installer consistently; it does not create Windows SmartScreen or public trust. To use a publicly trusted certificate, provide SYNAX_WINDOWS_PUBLISHER, CSC_LINK, and CSC_KEY_PASSWORD. Update manifest signing is configured separately through SYNAX_UPDATE_SIGNING_KEY and SYNAX_UPDATE_PUBLIC_KEY. Update feeds are isolated by platform and architecture. Latest advances only when macOS x64/arm64 and Windows x64 artifacts are complete; rerunning an older complete release does not promote it again.

Computer Use is available in the Electron desktop app through an app-hosted Cua Driver. Desktop packaging downloads a pinned Cua Driver 0.30.2 executable and verifies its SHA-256 before bundling; SYNAX_CUA_DRIVER_PATH may point to an already installed matching executable. Development mode uses that override or finds cua-driver on PATH (the executable must also be 0.30.2). On macOS, grant Synax Accessibility and Screen Recording permissions in System Settings, then relaunch Synax. The project settings page displays the Driver status and permission shortcuts. Cua starts asynchronously after the UI loads; a missing grant or incompatible binary does not block the rest of the app.

The default Auto strategy uses Direct Cua without a Jev account or network request. Jev-assisted operation is optional: set TYPESAFE_API_KEY in the environment that launches the desktop app, then enable Jev in the project Computer Use settings. The controller chooses from bounded semantic actions and verifies a fresh window state after each action. cua-perception visual-region parsing is optional and disabled by default; the visual extension is not bundled in the Synax installer.

Jev can also run through a configured provider instead of TypeSafe. Add an OpenRouter connection under Settings -> Providers (OpenAI-compatible format, Base URL https://openrouter.ai/v1, your OpenRouter API key), then select that provider for Jev in the Computer Use settings. OpenRouter serves the TypeSafe System One API at https://openrouter.ai/api, so Synax normalizes the connection base URL before the SDK appends /v1/systemone, and the connection API key is used instead of TYPESAFE_API_KEY. The Jev model field takes a System One model id such as jev-1.13, typesafe/jev-1.13, or ~typesafe/jev-latest, not a chat model id. The client.models.list() limitation noted by OpenRouter does not affect Synax, which never lists models. Leaving the Jev provider unset keeps the original TypeSafe behavior.

You can also start the two servers separately, for example when running the API in one terminal and the frontend in another:

npm run dev:local   # API only, port 3211, ~/.synax/web-dev
npm run dev:client   # Web only, port 5174, ~/.synax/web-dev

4. Configure and start working

  1. Open Settings and add a model provider, API key, and model.
  2. Import a local project directory.
  3. Start a conversation with the built-in Synax agent.

Ports

Variable Standalone default Development profile Purpose
PORT 3210 3211 API port
WEB_PORT 5173 5174 Web development server port
WEB_HOST 0.0.0.0 inherited Web development server bind address

The standalone defaults apply to start:local. The development profile defaults are applied automatically by the existing dev, dev:all, dev:local, dev:client, and dev:desktop commands. You can still override them in the shell that launches the development scripts.

GitLab MR sign-in

Open Settings → GitLab sign-in, enter a GitLab hostname and a Personal Access Token with the api scope, then choose Verify and save. Synax connects through its built-in GitLab REST API client without requiring glab. Credentials are scoped to each host, encrypted in local configuration, and omitted from settings responses. You can test connections, replace tokens, and sign out.

Choose a GitLab remote in the conversation PR panel to read, create, and merge MRs, inspect Pipeline status, and resolve conflicts. GitLab API connections use HTTPS. Git push / fetch continue to use the repository's existing SSH or HTTPS credentials. Signing out removes Synax credentials without revoking the token on GitLab.

Local Git merge requests

Workspace Commit / Commit & Push checks for conflicts before staging. Identical changes and conflicts with an unchanged base side resolve directly; other text conflicts use the project's configured model, replacing only conflict blocks. Unavailable models, incomplete results, concurrent file edits, and binary or structural conflicts stop the commit and preserve the conflict state. Push checks the index, worktree, and every outgoing commit for conflict markers. Push alone does not create resolution commits; use Commit to resolve conflicts first.

Open Git from an imported project's header to create a local MR. Select a target and one or more ordered sources, using merge commits, per-source squash, or fast-forward-only. Synax prepares the entire batch in an isolated worktree before updating the local target.

  • Conversation merges run in a dedicated subagent. The parent keeps the task card and bounded summaries, waits by default, and can be released by an explicit background handoff.
  • Click a conflict file to open the Monaco three-pane workbench directly. Running merges are read-only; stopping permits draft edits. Stop/continue and cancel control the task while the subagent performs checks and applies the verified candidate.
  • Workspace text viewing and editing share Monaco. Markdown, HTML, SVG, image, PDF, audio and video previews remain available. Merge files beyond the edit budget are read-only; larger files use bounded byte pages.
  • Configure checks as an executable, JSON argument array and timeout. One-click presets can apply the candidate after every check passes. Checks execute project code; configure only trusted commands.
  • Updating a checked-out target requires explicit opt-in when creating the MR and a clean, idle target worktree. Stale branches and file revisions are rejected.
  • The optional Git Manager uses the configured model to inspect the bound MR and propose patches for review. It cannot directly publish branches or push. Manual MR works without a model.
  • Stopping an intelligent merge retains its checkpoint. Cancellation abandons it and removes its owned candidate worktree; failed cleanup is retryable, and an already applied target is never reset. Independent manual MRs retain drafts on cancellation. Local records live under the Synax data directory's git-mr folder.

Presets are user-triggered rather than scheduled. Unsupported structural conflicts, such as submodules, stop explicitly for external resolution. The feature does not push or delete source branches. Tracked .DS_Store files, merges from test/beta into feature branches, and dependency-version changes in test-branch pom.xml files are rejected.

License

Apache License 2.0

About

A local workspace for coding agents and codebase documentation.

Topics

Resources

Stars

14 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages

0