Development

Run asyncat from source, understand the codebase layout, and contribute.

Building from source

# Clone the repo
git clone https://github.com/asyncat-oss/asyncat-oss.git
cd asyncat-oss

# Install all workspace dependencies
npm install

# Rebuild native SQLite/Puppeteer modules for Electron's Node version
npm run electron:rebuild

# Run in development mode (hot-reload Electron + React UI)
npm run electron:dev

Development mode starts the backend server, builds/watches the frontend with Vite, and launches the Electron application. The app hot-reloads on file changes.

Other commands

Command	Description
`npm test`	Run the test suite across all packages.
`npm run lint`	Run ESLint across the workspace.
`npm run electron:build`	Build and package distributables for your current OS.
`npm run electron:build:mac`	Build macOS DMG package.
`npm run electron:build:win`	Build Windows EXE package.
`npm run electron:build:linux`	Build Linux AppImage / deb package.

Project structure

asyncat is an npm workspace with three main components:

asyncat-oss/
├── den/                  # Backend — Node.js + Express + SQLite
│   ├── src/
│   │   ├── agent/        # Agent runtime, tools, skills, ReAct loop
│   │   ├── ai/           # AI provider clients
│   │   ├── auth/         # JWT auth, user management
│   │   ├── db/           # SQLite schema + migrations
│   │   ├── integrations/ # GitHub, Google Calendar, Outlook, etc.
│   │   └── ...           # notes, kanban, calendar, files, config
│   └── package.json
├── neko/                 # Frontend — React + Vite
│   ├── src/
│   │   ├── components/   # UI components
│   │   ├── pages/        # Route pages
│   │   └── store/        # State management
│   └── package.json
├── electron/             # Desktop Wrapper — Electron
│   ├── main.js           # App entry, boot sequence, tray, IPC shortcuts
│   ├── backend.js        # Spawns backend as a child process
│   └── preload.js        # Secure IPC bridge
├── data/                 # Runtime data (SQLite DB, uploads, logs)
└── package.json          # Workspace root

Packages

Package/Folder	Role	Description
den	Backend Server	Express.js backend on port 8716. Handles REST API, WebSockets, auth, database, AI provider communication, and the agent runtime (ReAct loop, tools, skills, memory, scheduler).
neko	Frontend UI	React + Vite frontend on port 8717. The web UI — chat interface, workspace tools, settings, scheduler, kanban, notes, calendar. Builds to a static bundle loaded by Electron.
electron	Desktop Wrapper	Electron app container. Binds everything together. Spawns backend server automatically, creates the menu bar tray icon, handles global shortcut (`Cmd/Ctrl+Shift+A`) and native menus.

Contributing

asyncat is open source under MIT. Contributions are welcome — issues, pull requests, and feature discussions happen on GitHub.

Good first issues

Adding new tools in den/src/agent/tools/ — follow the existing pattern in any tool file
Adding or editing skills in den/src/agent/skills/ — skills are plain markdown with YAML frontmatter
Frontend improvements in neko/src/ — React + Vite, TypeScript throughout
Electron UI / Tray / Window management improvements in electron/

Before submitting a PR

Run npm test and make sure all tests pass
Run npm run lint for any lint errors
Run the dev build locally to verify the app boots without console errors