Proma: an open source desktop Agent for people who live inside long sessions

The problem Proma targets: context that survives more than one task

Most chat clients treat a conversation as disposable. Proma treats it as the unit that has to be organised. The README frames the whole product around one claim: better context produces a more capable Agent, and the application's job is to help you organise that context rather than to hide it.

The concrete mechanism is a three-level split. A project is a working area; inside it you keep project files and an AGENTS.md that constrains how the Agent behaves across that project. A session is one dialog box, and the README says a session should handle one specific small task. Session files are the throwaway references for that task, and anything you drag into the input box lands in the session folder.

Who this is for is stated fairly bluntly. Proma is aimed at professional users and heavy Agent users, and the commercial comparison table is written for people who already understand model channels, API keys and plan compatibility. If you open a chat window a few times a week, the project/session/memory scaffolding is overhead you will not repay.

How Proma is put together: Electron, Bun workspaces and a three-column UX

The repository is a Bun workspace monorepo. package.json declares workspaces for packages/* and apps/*, and the dev script filters to @proma/electron, so the desktop shell is an Electron app and the rest of the tree is supporting packages. The root package is private, and the scripts you would actually use are dev, electron:build, dist:mac, dist:win and dist:linux.

There is a notable dependency set. The overrides block pins @earendil-works/pi-agent-core, pi-ai, pi-coding-agent, pi-server and pi-tui to 0.85.1, and patchedDependencies applies local patches to @earendil-works/[email protected] and [email protected]. That tells you two things. The Agent runtime is a pinned external dependency rather than something developed inside this tree, and the project maintains its own patch on top of it. If you plan to build from source, those patches are part of your build, not an optional extra.

The UX split is described in the README as left, middle, right. The left column manages sessions and main entry points. The middle column is where the Agent produces output and where you interact with it. The right column holds everything auxiliary: project files, file changes, document previews, sub-session interaction, the embedded browser, the terminal, Obsidian, calendar, Todo and Skills. The stated intent is that the right side exists to improve what happens in the middle.

Sub-sessions and exploration: the two features that differ most from a plain chat client

Sub-sessions are the project's answer to sub-agents. The README describes them as having a cleaner context than a traditional sub-agent, being a persistent environment you can iterate in, with freer model choice. The pattern it names is adversarial: a main session that repairs and a sub-session that keeps reviewing. You can view the main session and a sub-session side by side.

Exploration mode is the second idea, and the README is explicit that it is exploration rather than forking. After the Agent finishes output, you can create branches that reuse the preceding context, run as many as you want in parallel, and then bring them back to the main line with a button in the exploration panel's top right. The stated reason for the naming is that you may not want a half-formed judgement to pollute the main session's context, but you do want to keep the useful part.

These are also where the documentation thins out. The README explains the intent and the screenshot flow, but it does not document what happens to a sub-session's context when the parent session is compacted, or how exploration branches are stored on disk. Those are the questions I would want answered before relying on either feature for work I cannot redo.

Installing Proma from GitHub Releases and starting a first project

The README points at GitHub Releases for the open source build. The listed artifacts are macOS Apple Silicon, macOS Intel, Windows, an Ubuntu/Debian x86_64 .deb and a Linux x86_64 AppImage. There is no package manager install documented, so the install step is downloading the artifact for your platform and running it. Linux users are pointed at docs/linux.md for installation, security boundaries and support scope.

If you are building from source instead, the repository uses Bun. The root scripts are the entry point:

bun install
bun run dev

The first command installs the workspace dependencies, including the pinned @earendil-works/pi-* packages and the patched node-pty. The second runs the Electron app in development mode. A production build for your platform goes through the dist scripts, for example:

bun run dist:mac

On first run you supply your own provider and API key, because the README's comparison table lists self-managed provider channels and API keys as the open source model path. The README's suggested first real task is to create a project, then ask the Agent to write an AGENTS.md for that project and to read your sessions from the past half month or month to extract memories. That is a fair smoke test: it exercises project files, the AGENTS.md convention and the memory index in one pass. The README names MEMORY.md as the memory index, with the individual memories underneath it.

One more script worth knowing before you file a bug:

bun run typecheck
bun test

The open source build is deliberately the slower one

This is the limitation to read before anything else. The README states that the team's capacity and time are limited, so it chose to reduce the pace of feature updates and iteration for the open source version and focus on the commercial one. The comparison table repeats it: the open source build gets necessary updates and fixes, the commercial build gets a faster cadence and timely fixes.

That is an unusual thing to write down, and it should shape how you evaluate the project. The last push to the repository was on 2026-09-09, and the most recent release listed is v0.19.52 on the same date, so the tree is not abandoned. But a recent push is not the same as a commitment to the open source feature line, and the README says outright that it is not.

The second limitation is trust in your model link. The table says open source users have to assess their own provider's security, protocol compatibility and stability, and that if you route through a third-party relay you also have to judge the extra trust and data-handling risk yourself. Proma does not remove that decision; it moves it to you.

The third is context economy. The README notes that too many Skills and MCP servers degrade Agent performance, which is why Proma scopes them per project, and it admits the cost: it requires more attention from the human. If you wanted a tool that configures itself once and forgets about it, this is not that tool.

Where Proma is the wrong choice, and what a plain coding CLI does differently

If your work is a single repository, a single task and a terminal, a coding agent CLI is a smaller tool for the same job. It runs where your code already is, it does not ask you to define projects and sessions, and there is no desktop shell to keep updated. Proma's advantage, an embedded visible browser and terminal that the Agent can drive, plus document preview and annotation, matters when your task spans reading a PDF, checking a web page and editing a file in one thread. If your task never leaves the repository, that machinery is weight.

The sharper comparison is against Proma's own commercial build, because the README makes it a real alternative rather than a marketing page. The differences are concrete: the commercial build logs in and gives you Proma's built-in model channels while still allowing third-party configuration; it offers Proma Cloud API keys with quota limits that you can wire into your own applications; it adds team quota allocation with monthly auto-assignment and usage records; and in the enterprise tier it distributes Skills organisation-wide so members install nothing. The open source build is workspace-local Skills that your team has to distribute by hand.

So the honest framing is not open source versus closed source. It is self-managed model plumbing versus a hosted link, and hand-rolled team distribution versus an admin panel. The README says you can install the commercial build over the open source one and your local data is kept, which lowers the cost of starting open source and deciding later.

Licence, upgrade cost and what the repository does not document

Proma is licensed AGPL-3.0. The practical consequence for most readers is the network clause: if you modify Proma and let users interact with it over a network, the AGPL's source-availability obligation is the thing to examine with your own counsel. Nothing in the README describes a separate commercial licence exception, so if you intend to embed Proma in a hosted product, treat that as an open question rather than a solved one. This is not legal advice.

Upgrade cost splits by install path. Release artifacts mean you replace the application, and the README says installing the commercial build over the open source one preserves and inherits your data. Building from source means you carry the pinned @earendil-works/pi-* versions at 0.85.1 and the two patches under patches/, so a dependency bump is a rebase of your patches, not a version range you can float.

What the repository does not document is as important. There is no rollback procedure in the README, no migration notes between the v0.19.x releases, and no statement about what happens to project memory or AGENTS.md if you move between the open source and commercial builds beyond the claim that data is preserved. If your projects carry months of accumulated memory, verify that on a copy before you switch.

Editorial conclusion

Adopt Proma if you are an Agent-heavy user who wants a visible terminal and browser inside the same window as the conversation, and you accept configuring your own model provider and API key. Do not adopt it if you need a vendor-managed model link, team quota administration or a fast open source release cadence: the README states the open source build deliberately moves slower than the commercial one. Before installing, read docs/linux.md if you are on Linux, and decide whether you are willing to move to the commercial build later, since the README says installing it over the open source version keeps your local data.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. Project website
3. proma-ai/Proma on GitHub
4. README
5. Releases