Open it up.
Make it yours.

The desktop app, backend and interface live together in one npm workspace.

Run from source

You need Node.js 22 (22.13 or later) or Node.js 24 or later, npm and Git.

git clone https://github.com/asyncat-oss/asyncat-oss.git
cd asyncat-oss
npm install

# Backend, frontend dev server and the Electron app
npm run electron:dev

# The same, with Developer Tools opened automatically
npm run electron:dev:tools

In dev mode, Electron loads the interface from the Vite dev server on port 8717, so you get hot module replacement. It uses the backend that npm run dev:backend runs on port 8716 in Node's watch mode, which restarts when you edit den/. Developer Tools are also in View → Toggle Developer Tools.

To work in a regular browser instead, npm run dev starts only the backend and the Vite dev server. The backend runs on system Node.js, so its native modules must match that version. See Troubleshooting if one fails to load.

Tests

npm test -w den          # backend
npm test -w neko         # frontend
npm run test:release     # desktop app and release scripts
npm run test:e2e         # end-to-end smoke test in a headless browser

The end-to-end test starts a throwaway copy of Asyncat, with its own data folder and ports, a fake model, a fake MCP server and a fake ACP agent. It clicks through chat, projects, agents, Cats, connectors, Privacy & safety, training, Files and the main pages. It needs a Chromium-based browser (Chrome, Chromium, Edge or Brave) and never touches your data.

Project structure

Directory	Role
`electron/`	The desktop shell: boot sequence, windows, tray, global shortcuts, Quick ask, the optional desktop pet, updates, and starting the backend.
`den/`	The Node.js / Express backend and agent runtime, with SQLite storage.
`neko/`	The React / Vite interface.
`scripts/`	Install, icon, Node bundling, end-to-end and release scripts.
`build/`	Windows installer customization.

Inside den/src

Folder	What it holds
`agent/`	The agent runtime, tools, skills and skill suggestions, sessions, the command sandbox, copies, profiles and the ACP client.
`ai/`	Providers, local engines, and the chat, agent and training routes.
`cats/`	Cats: their store, clock and triggers, runs and inbox.
`connectors/`	MCP connectors: config, OAuth and download checks.
`knowledge/`	Project and agent files: text extraction, search and context sizing.
`made/`, `storage/`	What agents made, and the places, sizes and clean-ups behind Files.
`media/`	Voice and picture setup, and the picture gallery.
`privacy/`	Blocked sites, export everything and delete everything.
`search/`	Universal search, including words inside chats.
`setup/`	First-run setup and the local model it offers.
`training/`	Guided training: data, plans and adapters.
`update/`	Update status and graceful restart.
`importers/`	ChatGPT and Claude exports.

Other folders cover the browser history, config and secrets, the database, notes, integrations, users and projects.

Inside neko/src

Folder	What it holds
`CommandCenter/`	Chat and agent runs.
`projects/`, `Agent/`	Projects, your agents and the agent editor, and coding agents.
`Cats/`, `Connectors/`	The Cats pages and inbox, and connector settings.
`Models/`, `Training/`	Providers, local models, voice, images, and guided training.
`files/`	The Files page.
`sidebar/`	The sidebar, Claude Code and Codex sessions, and `Cmd/Ctrl+K` search.
`welcome/`, `quick/`	First-run setup and Quick ask.
`Settings/`, `Tools/`	Settings tabs, the tools and skills browser, and the Memory page.

Package the app

# Build for your current platform
npm run electron:build

# Platform-specific packaging
npm run electron:build:mac
npm run electron:build:win
npm run electron:build:linux

Packages go into the release/ directory. Build on the same operating system and CPU architecture as the target: the backend includes native SQLite and Canvas modules, so relabeling a cross-compiled package is unsafe.

Publish a release

The versions in package.json, den/package.json and neko/package.json must match the tag. Bump all three, then validate them before tagging (replace vX.Y.Z-beta.N with the new version):

npm install --package-lock-only
npm run release:validate -- vX.Y.Z-beta.N
git tag vX.Y.Z-beta.N
git push origin vX.Y.Z-beta.N

The release workflow builds and verifies each native package on a matching runner, creates SHA-256 checksums, and publishes all installers to one GitHub Release. Tags with a suffix such as -beta.1 become GitHub prereleases.

Contribute something useful

Start with a focused issue or change. Useful contributions include a reproducible bug report, clearer documentation, a new skill, or an improvement to the app.

Run the tests for the parts you changed, start the development app, and try the behavior yourself.

Explore the repository →

Open it up.Make it yours.