Development
Stack
Electron 44 · electron-vite 5 · React 19 · zustand 5 · TypeScript strict · vitest. Layout - regular CSS with tokens in oklch, without UI libraries (color system -
design/colors.md). External agents connect via ACP (@agentclientprotocol/*), built-in - by its client to the OpenAI-compatible API. Main process storage - JSON files in userData and SQLite via builtin node:sqlite
(without native modules), see "Storages" below. Terminal - node-pty in a separate process and xterm.js in a window (docs/terminal/).
Teams
npm install
npm run dev # hot boot window
npm run typecheck # tsc for main and renderer
npm run lint # ESLint: warnings do not block validation yet
npm test #vitest: 5922 tests
npm run build # electron-vite build → out/
npm run pack # DMG: dist/Pulse-<version>-arm64.dmg
npm run smoke # smoke test of graph and ACP event merging
From under another Electron process, the window is launched with the variable cleared:
env -u ELECTRON_RUN_AS_NODE npm start
Separate data profile (does not affect your worker):
env -u ELECTRON_RUN_AS_NODE npx electron . --user-data-dir=/tmp/pulse-test
Structure
src/main/ Electron main: IPC, live agent sessions, git, transcripts, settings, log
db.ts SQLite applications: database opening, WAL, migration (node:sqlite)
terminal/ pty-host (node-pty), session manager, block parsing, agent command runner,
command history (history.ts is the only SQLite application database for today)
agents/ agent registry, ACP session, built-in API agent, tools, sandbox
swarm/swarm coordinator, worktree participants and merging
mcp/ stdio client for external MCP servers
memory/ repository memory
ai/ AI application service (task names, commit messages, translations)
src/shared/ pure logic and types for both processes (graph, summaries, policies, budgets,
context, versions of instructions, reports) - covered with tests
src/renderer/ React: board, graph, transcript, diff, terminal, settings
src/preload/ IPC bridge
cloud/ update and report server (Fastify + SQLite)
library/ catalog of skills and roles
mcp/ Pulse MCP server for external agents
scripts/ assembly, signature, screenshots, auxiliary scripts
Code rules: comments in Russian and to the point (why, not what), files up to ~800 lines, no mutation of general structures, all pure logic is in shared/ with tests.
Main process storage
Two types, and the choice between them is based on the form of the data, and not on taste:
| View | Than | Why | Examples |
|---|---|---|---|
| JSON snapshot | persistence.ts: writeJsonAtomic (writing to a temporary file, .bak previous version, rename) and readJsonRecover |
a state that is read in its entirety and rarely changes; the entire file is rewritten every time it is changed | pulse-tasks.json, pulse-settings.json, pulse-sessions.json, secrets.json |
| SQLite | db.ts: openAppDatabase(file, migrations) - built-in node:sqlite (Electron 44, DatabaseSync, there is FTS5), WAL, table migrations with identifiers |
logs that grow one line per event and are read selectively: you cannot rewrite the entire file for the sake of one line | pulse-terminal-history.db — history of terminal commands (terminal/history.ts) |
Rules for each database: its own file in userData (to the repository and worktree - never), list migrations and only forward, everything that may contain secrets is under safeStorage
as in secrets.ts, with an honest flag “no encryption”, where there is no keychain. Native SQLite modules (better-sqlite3) are not included in the application: npmRebuild: false, they are not rebuilt under ABI Electron; better-sqlite3 lives only in cloud/.
Candidates for translation to SQLite if JSON becomes too small (the owner's decision has not yet been made): activity feed (pulse-activity.json grows without limit), session transcripts (currently JSONL with page reading), time and expense metrics. Assistant db.ts general - the second database is opened by the same function with its own list of migrations.
Repository Areas
The tree above is for a person. For the agent, the same structure is written by machine: a map of areas in src/shared/areas.ts. From it the root is collected CODEOWNERS, from which the label names are taken area:*, and according to it the editing area is calculated by paths, and is not guessed by the name of the branch. Analysis of organizations warpdotdev and unslothai (docs/backlog.md) showed that it is not the boundary between repositories that saves context for the agent, but the map within one.
| Region | What is this | Paths | Owner |
|---|---|---|---|
core |
common logic and types for four processes | src/shared/ |
owner |
app-main |
main process and IPC bridge | src/main/, src/preload/ |
owner |
app-ui |
application window | src/renderer/ |
owner |
mobile |
web remote and Android wrapper | src/mobile/, android/, capacitor.config.ts |
owner |
cloud |
server: login, licenses, updates, reports | cloud/ |
owner |
site |
site and its checks | site/ |
owner |
library |
catalog of skills, roles and interface blocks | library/ |
owner |
mcp |
Pulse MCP server for external agents | mcp/ |
owner |
build |
build, signature, installers, root configuration | scripts/, build/, resources/, root |
owner |
qa |
end-to-end runs and agent skills | scripts/e2e/, .claude/ |
second developer |
ci |
both sets of checks | .github/, .gitlab-ci.yml |
owner |
docs |
documentation, README, CHANGELOG | docs/, root *.md |
owner |
swarm |
swarm 24/7: orchestrator, performers, memory; apps/pulse-server not connected yet (see its README) |
packages/, apps/, services/ |
owner |
Borders are not made up. Each area is called modules docs/codemap/codemap.json - those that are calculated by code. src/shared/areas.test.ts checks both sides: an area without a module is a fiction, a module without an area is a hole, both of them color the test. Therefore, a new top-level directory cannot be created silently: it will remain without an area, and this will be visible.
qa - the only area not for the owner, and this is measured, not polite: in the log from August 1 scripts/e2e/ — 29 edits out of 29 by the second developer, .claude/ — 16 out of 17. In all other areas, his edits are single compared to the owner’s hundreds.
CODEOWNERS
The file lies at the root, not in .github/: GitLab is looking for CODEOWNERS at the root, at docs/ and in
.gitlab/ - catalog .github/ not on this list, but work has been going on GitLab since September 24, 2026 (git.avacloude.ru/avateam/pulse). Both hosting providers read the file from the root.
Assembled from a card, cannot be edited by hand:
node --experimental-transform-types --import ./scripts/ts-loader.mjs scripts/labels/codeowners.mjs
node --experimental-transform-types --import ./scripts/ts-loader.mjs scripts/labels/codeowners.mjs --check
What is he doing now: serves as a repository map for human and agent. What it doesn't do: It doesn’t block anything and doesn’t ask for review. On our GitLab (Free edition), code owners have the option of paid plans, and the file does not work there at all: no requests for reviews, no marks in MR. He asked for a review on GitHub, but PRs are no longer opened there. main in GitLab is protected only from push --force and does not require approval from pushers below the Developer role.
The price of enabling protection before turning it on. All 14 existing PRs are opened by a second developer, not the owner. With protection and the “Require review from Code Owners” checkbox, each of its PRs will come before the owner’s review - this is the point of the gate, but this is also a complete stop of work if the owner does not read the PR daily. The reverse side is thinner: on areas with one the owner has no one to approve this owner’s own PR - GitHub does not consider the author a reviewer of his PR, and only an administrator can unblock it, bypassing the rule. Of the thirteen regions, twelve are now exactly like this. Therefore, the protection is turned off, and whether to turn it on is the owner’s decision, and not a consequence of the appearance of the file.
@-the names in the file match the GitLab accounts: when moving on September 24, 2026, the owner and the second developer received the same logins there (NameLucky2205, avigdorsky). Therefore, if the server ever switches to a paid edition, the file will work without changes.
Tags
Labels are named by areas one to one: area:core, area:app-main, ... There are thirteen of them, they all have the same color - with thirteen shades the list of labels is less readable than with one.
A person places them; which ones are suitable for a particular MR, the script calculates according to the editing paths. The default hosting is our GitLab (git.avacloude.ru, project avateam/pulse), token - GITLAB_TOKEN with the area api (same as glab):
GITLAB_TOKEN=… node --experimental-transform-types --import ./scripts/ts-loader.mjs \
scripts/labels/sync.mjs areas --pr=<MR>
Started with the same script, and by default it does not create anything — prints the plan and exits; creates only with --apply:
GITLAB_TOKEN=… … scripts/labels/sync.mjs labels # plan
GITLAB_TOKEN=… … scripts/labels/sync.mjs labels --apply # create
GH_TOKEN=$(gh auth token) … scripts/labels/sync.mjs labels --host=github # GitHub mirror
Tags status: …, priority: … and size: … (board “Tasks”, see docs/tracker.md) are not included in the map of areas: the script lists them as foreign and does not touch them.
The script does not know how to delete tags intentionally: they are already on the hosting pilot, blocked,
promised from the last wave, the map doesn’t know about them, and demolishing someone else’s markings at the same time is a loss, not a cleanup. He only lists other people's marks.
Agent marks (agent:reviewed, agent:stale-rebase, agent:duplicate,
agent:draft, agent:blocked) are described in the map, but are marked as unready and do not start by default. There is only one reason, and it is more important than convenience: there is no agent who issues them yet - these are stages 1–3 from docs/backlog.md. Started in advance agent:reviewed would mean “there can be a review agent,” but there isn’t one. You can still turn them on with a flag --all, and the script will tell you who is missing.
Rhythm
Weekly milestone of the form “2026 week 39 (September 21–25)” - Warp rhythm: week with dates, no closing. The script can count and start them, but by default it only shows the plan:
GITLAB_TOKEN=… … scripts/labels/sync.mjs milestones --weeks=4
There is no reason to start them now, and the script says it out loud. The tracker already has ten issues by version (0.31 - release does not diverge … 1.0 - have something to sell; moved from GitHub to GitLab on September 24, 2026), and tasks are assigned to them. There is only one milestone for a task, so weekly milestones will not be added to the versioned ones, but will compete with them: you will have to keep in mind the rule of which one to set. It makes sense to start the rhythm together with the agent of stage 2, who will begin to lay out the plan by week - and then choose one out of two.
Agent skills
Claude Code sessions and the "/" menu in Pulse Composer read the same files −
.claude/skills/<name>/SKILL.md. Format - Agent Skills: name equal to the folder name,
description says what the skill does and when to read it, the body is no longer than 500 lines, details are in references/. This checks src/shared/repoSkills.test.ts.
| Skill | When to read |
|---|---|
pulse-projects |
before any work with issues, MR, GitLab board, releases, tags and CI, before each commit and push: where everything is (GitLab is the main one, GitHub is the mirror), who contributes what, how not to waste minutes GitHub Actions and your runner’s queue |
steward |
before any push and during MR events: checks, commit style, red CI, conflicts |
pulse-ds |
before any edits to src/renderer, src/mobile, site/styles and before changing the design system itself: where to get the component and token, guards, codemod scripts/ds-codemod.mjshow to add the DS version and update the storefront |
e2e |
stand scripts/e2e/: how to run, what it consists of, selectors for each script |
terminal-code |
editing the terminal: where everything is, main traps and windows, how to add a channel term-*what to add in documents |
terminal-invariants |
editing or review of the terminal: secrets, term-run, deny, honesty - rule → test |
terminal-verify |
prove terminal editing on a live application: order of checks, reading the screen in words, waiting for a fact |
terminal-quality |
what evidence does editing a terminal/agent bring: an invariant from the registry, a quick test, a live check, a stand step, recording a found bug in the corpus; levels check:* |
terminal-spec |
M2.5+ milestone point before code: invariants, commit context, criteria with tests; template in references/ |
The rule for new skills is a trap, not a map: the skill records what the sessions have stepped on twice, and links to a file that makes the statement true (workflow, script, test). The code description is the first to become obsolete - its place in docs/, not in skill.
Interface - according to the design system
Any edit in src/renderer, src/mobile, site/styles — according to Pulse DS (owner’s decision 02–03.10.2026; from 03.10 primary coverage 100%, docs/design/progress.md). Briefly: button - components/ui/Button, status - ui/Badge, menu/prompt/window - ui/Menu, ui/Tooltip, ui/Modal, graphics - ui/charts; color is just a token --color-*, offset and radius - --sp-*/--r-*, size - --fs-*; the surface is a plane with light, not a frame; icons - one set ui/icons.tsx. No component - first guide in docs/design/system/components/, then the component, then the use. Guardians in npm test (cssVars, cssDebt, dsCodemod) they are retreating; repair -
node scripts/ds-codemod.mjs <file>. Complete rules and how to develop the system - skill .claude/skills/pulse-ds.
Tests
- Unit and integration -
vitestnext to the code (*.test.ts). - Through run
npm run e2e(afternpm run build) is a real application fromout/with a separate profile, local cloud fromcloud/and a fake OpenAI-compatible model server. Two files:run.mjs— login by mail with code, task from composer, agent turn, diff, policy;lifecycle.mjs— task life cycle in two repositories: transfer and deletion of files, acceptance with infusion intomainand without, failure, merge conflict, stash of human edits, archive, deleting a task from worktree, restarting the application;projects.mjs— three repositories and transitions between them: tasks go to the model simultaneously, dashboard, activity, worktree and graph converge with the disk, plus failures: silent model and Stop, provider error, missing working folder, full context, “Ask” after restart;collab.mjs— collaboration: a swarm of three agents with tasks in a pulse-assign block, reports and merging of participant branches, a swarm graph, wave cancellation, a file editor with external change and conflict, a terminal in a working copy, a shared team board via a local cloud with offline and delayed unpublishing;governance.mjs— human control over the agent: a policy rule from the settings stops the team, the token limit does not allow the next turn and is removed by editing the limit, the quality inspector gives an assessment from the report, and a response without an assessment does not become a report;review.mjs— daily movements around the agent: skill through “/”, search on the board, launch from the Todo card, comment on the file with sending to the author and closing by the person, commit from “Working changes”, hotkeys;extensions.mjs— extensions around the agent: the MCP server via stdio from the settings reaches the built-in agent and its tool is actually called, the schedule with “Run now” creates a task and the agent does it, the expense page converges with the number of turns and sessions;resilience.mjs— resistance to failures: model stream interruption, application killed in the middle of a long command, Stop on a long command without zombie processes, command output in megabytes, context compression with summary, damaged session storage;gitops.mjs— git by human hands on top of the agent’s work: Git tab (branches, history, pending changes), drift and infusion when main has moved ahead, switching a working copy to another branch and honest refusal to a busy main, interactive rebase, AI merge conflict resolution, pre-commit hook that interrupts a commit;ui.mjs— shell and interface state: a board of ten tasks in the list, columns and on the dashboard, filter by status, composer draft and task notes, search by transcript, theme and scale, key rebinding, restart with all this, minimum size window without horizontal scrolling;mobile.mjs- mobile remote control fromout/mobilein a separate Chromium against a real local cloud relay: pairing via a link from the QR, confirmation of the fingerprint on the machine, board and session on the phone, progress and permission from the phone, “Abort the turn”, turning off and on the remote control on the machine, recall of the phone. Between the phone and the cloud - a reverse proxy of the stand in the role of nginx (one entry point for statics and API);handoff.mjs— transferring a task by file between two clones: sending with context, importing by a colleague, reply sending merged into the original task; check before sending catches the secret in an uncommitted file and requires explicit confirmation; task audit export; The “at a given time” schedule works itself. System file dialogs are replaced in the main process throughapp.evaluate;updates.mjs— updates via the local cloud release server: upload to/admin/releasesunder the admin token, “Check for updates” without releases and with an old release, “New version of Pulse” card in the notification center, download with sha512 verification, file corrupted on the server, beta channel;cabinet.mjs- personal cloud account in a separate Chromium against the application: login by email and password, application machine in “My Devices”, “Allow phone” from the account includes a switch in the application, renaming, recall of the machine (the application names the reason) and return, access code from the admin panel and registration via/signup, exit;race.mjs— agent race: the “Team” chip launches two authors in its working copies (the second is a profile on the same local model, the stub recognizes it from the profile instructions), the “Race” panel as a result of the task: without commands there are no places to check and the reason is named, after running the checks - places with a basis, “Take this result”, “Remove from the race” with branches and acceptance, working and stopped participants separately from the losers;execution.mjs- Linux sandbox (bubblewrap; without it, scripts are honestly skipped): writing outside the working folder is refused, goes inside, the network ban is explained in words and removed in Policies; closing a window with running tasks - a question with three answers via a spoofed onedialog.showMessageBox, “Continue without window” with a report when the window returns afterapp.emit('activate'), “Stop and exit” via exit confirmation;cycle.mjs— a circle of group work with two copies of the application on the same cloud (author and reviewer with different profiles): general project, publication, “For acceptance”, invitation code, “Return for revision” with mandatory comments, return to the author’s board and to “Needs attention”, revision and “Accept”, the verdict without communication with the cloud waits in the queue and arrives after its return. Without a screen, it restarts itself under Xvfb, so it also works in CI on Linux. Scripts inscripts/e2e/, screenshots and log - inPULSE_E2E_OUTPUT(default temporary folder),PULSE_E2E_VERBOSE=1prints a log as he goes. Playwright comes fromsite/node_modules. There is no need to run real credentials and you cannot put them there. - Live runs (swarm, policies, MCP, sandbox) - scripts on Playwright + Electron in the scratchpad folder of the session: launch the application with a separate profile and model mock server.
- Before release:
npm run typecheck && npm test && npm run build.
Assembly and signature
- Config - block
buildinpackage.json. In asar onlyout/**andpackage.json,node_modulesunpacked: ACP adapters are launched by child processes. scripts/after-pack.cjssigns the application with a local certificate «Pulse Dev» (created oncescripts/make-signing-cert.sh), otherwise ad-hoc. A permanent signature is needed to make macOS remember “Always Allow” for the keychain.scripts/pack-cleanup.cjsremoves the unpacked copy of the application so that a second Pulse does not appear in Launchpad.- The finished DMG is about 420 MB (inside Electron and adapters).
- Installer window background draws
node docs/brand/tools/dmg-background.cjs(Chromium via Playwright, also works on Linux): writesbuild/dmg-background.pngand@2x.png, TIFFs from the pair are assembled by electron-builder itself on Mac. The script crashes ifbuild.dmginpackage.json(slots, icon size, background path) has moved away from the background or the text has dropped below the Finder status bar. Details - docs/brand/README.md.
Assembly for other systems
npm run pack builds macOS for Apple Silicon. After connecting Mac runners with tags
macos and macos-intel and installations PULSE_MAC_RUNNERS_READY=1 GitLab launches itself
macos arm64, then macos x64. Until the variable is enabled, both jobs are manual and the conveyor is not running. Locally Intel - pack:mac-intel. Windows x64 and Linux x64 are built in GitLab CI on Timeweb: pipeline main with variable INSTALLERS=1 (Build → Run pipeline; it runs at night according to the schedule) or the ▶ button for the task. EXE, ZIP, AppImage and deb are in the GitLab Package Registry; the artifact contains checksums and the package version. Only the installer tested for Wine gets into the Windows registry: the unpacked assembly reaches the start line (scripts/ci/smoke-launch.sh), and the installer is installed quietly, the installed copy is launched, placed on top and cleanly removed (scripts/ci/smoke-install.sh). Wine does not show windows or questions from the uninstaller - they are checked manually on real Windows. Script scripts/stage-windows-codex.mjs packages the Codex Windows binary from the committed version and checks SHA-512. Linux locally - pack:linux. GitHub Actions are disabled in the mirror settings.
Details on the systems are in Platforms.
Release version
- Update
package.json,CHANGELOG.md(what has been done and what's next), the version badge in the README and the first article insite/src/pages/changelog.html. Build a website (npm run build --prefix site) and include it in the same commitsite/changelog.htmlandsite/scripts/version.js. npm run check:changelog --prefix site, thennpm run typecheck && npm test && npm run build.- Submit commit and tag
vX.Y.Zin GitLab. GitHub will receive the mirror automatically; GitHub Actions are disabled. Start the conveyormainwith variableINSTALLERS=1. DMG can be compiled locally on a Mac of a suitable architecture, Linux packages on Linux x64. - Download the EXE and ZIP from the GitLab Package Registry to your release directory. Before publishing, check the version, Windows CLI content, and release metadata signature. The Android package will require a separate migration of the build and signing secrets to GitLab; the tag itself will not collect it.
- Roll out the cloud:
cd cloud && ./deploy.sh. Before uploading files, see "Order" below. - Upload ready-made platforms to the update cloud:
cd cloud && PULSE_PLATFORMS="win32-x64" ./publish-release.sh <version> <directory> "<note>". Add other platforms toPULSE_PLATFORMSonly after receiving their packages. The token is taken fromcloud/.deploy/admin.env. Backing up and restoring a separate manifest signing key is described in instructions. - Upload site:
cd site && ./deploy.sh. The script rebuilds the page and checks its first article againstCHANGELOG.mdand version of the application before downloading. The download block takes the build version from the update server itself, and the badge in the header comes fromversion.js.
The order of steps 5–7 is required: cloud → packages → website. platform android only the new cloud knows (cloud/src/routes/releases.ts), and it corresponds to both the display script and the card on the site. You cannot upload a package before the cloud rollout: /admin/releases will answer 400
invalid_platform. Rolling out the site before the cloud is worse: the “Android package” card is already in the collected site/download.html and asks /releases/latest?platform=android every time you open the page. The old cloud will answer 400, the card will say “the package is not being released yet” - the page will confidently tell lies about what the release is for. The reverse order is harmless: no one has yet asked for a cloud with an uploaded package and an old website.
Version rule: patch for each delivery (0.22.1, 0.22.2...), minor - only for a milestone (closed plan, new large block of capabilities).
cloud
cloud/ — Fastify + SQLite: authorization (mail, GitHub OAuth), licenses, update server (/releases/latest, /admin/releases) and receiving bug reports (/reports,
/admin/reports). Deploy: cd cloud && ./deploy.sh (build → rsync → restart → health).
Screenshots for README
scripts/ and scripts in scratchpad raise an application with a demo profile (a copy of data without a personal one, a swarm task on a mock model) and shoot showcase screens 1440x900 in
docs/screenshots/. After noticeable changes to the interface, the pictures should be reassembled.
Application, cloud and site checks
Node.js 24. The application has cloud/ and site/ your lock files:
npm ci
npm ci --prefix cloud
npm ci --prefix site
npm run typecheck
npm run lint
npm test
npm run build
npm run typecheck --prefix cloud
npm test --prefix cloud
npm run build --prefix cloud
npm run build --prefix site
node site/tools/mobile.mjs
npx --prefix site playwright install chromium
npm test --prefix site
The last command starts a temporary cloud and website on loopback ports 44100/44173, checks for browser login, cross-tab token updates, accessibility and links, then stops the servers and deletes the test database. The production server is not affected. From September 24, 2026, the main set of checks is .gitlab-ci.yml on your GitLab runner: each merge request, main and branches claude/* (without e2e and smoke interface check - they need a separate image). On GitHub, where the mirror brings main, it performs the same checks
.github/workflows/checks.yml on push in main (and on pull request - but PRs are no longer opened there) - except for PR drafts (running begins when translated to "ready") and changes only in files on which checks do not depend: log, interface parsing, unpublished documents, README, CHANGELOG, CLAUDE.md (list and how it is checked - src/shared/ciPaths.ts). A merge PR whose tree matches the verified green PR head does not receive a full run: this solves the problem merge-gate. It also checks that the PR went to main, the database was not changed and there was no force-push in main while the PR was open: the PR run checks the test merge with the database at the time of the event, and not the head (src/shared/mergedPullRequest.ts). After the force-push main, the gate will not be fully run back. Test that started reading a file from docs/ or .claude/, must return this path to the list, otherwise the file will be edited in main without running.
The queue of runs is divided according to the author of the head commit: your push cancels only its previous pass, someone else’s push reaches the end. Who was left without a green check shows
.github/workflows/contributors.yml twice a day and by button; the same locally -
GH_TOKEN=$(gh auth token) npm run ci:contributors. Rule - src/shared/contributorCommits.ts, there is also a list of required tasks.
Npm cleans caches on runners .github/workflows/cache-cleanup.yml — after installer builds, when closing PR and once a day. Rule (src/shared/actionsCachePolicy.ts): only keys with hashes of current lock files remain on main, caches of closed PRs and everything outside main is deleted, other people’s keys are not touched. Non-delete plan:
GH_TOKEN=$(gh auth token) npm run ci:caches -- --dry-run.
The site is stored in site/; documentation is collected from docs/, version - from root
package.json. site/deploy.sh also collects and publishes a web console for /mobile/.
/login, /signup, /account maintains the site; /auth/*, /license*, /relay/*
and administrative APIs - cloud. Cloud-based HTML pages remain a fallback interface for siteless installations.