-
Notifications
You must be signed in to change notification settings - Fork 0
App or Tool
Pick the shape before you write code. The choice decides where every file goes.
A tool is code the orchestrator finds. An app is code the orchestrator is.
| Tool | App | |
|---|---|---|
| Lives in | its own repository |
apps/ in this repository |
| Frontend built by | its own Vite project | the shell's vite.config.ts
|
| Frontend served from | its dev server, or helve-tool://
|
the shell's own origin |
| Rust half | a child process, over the standard streams | a module in src-tauri/src/apps/
|
| Missing, unbuilt, or out of date | yes | no, because the code is in the binary |
Write an app when the surface shows what the orchestrator already owns: the stack resolved at boot, the checkout, the open project. Home and File Explorer qualify. A process boundary in front of that data ships an IPC hop to talk to ourselves.
Write a tool when the surface has its own domain, its own release cadence, or ships apart from the orchestrator. Every entry in helve.toml is a tool for one of those three reasons.
Both shapes speak one protocol. An app frontend calls invoke("files/list") through @helve/bridge. The echo tool frontend calls invoke("echo") the same way. Neither frontend knows which host answered.
That symmetry has a purpose. It lets you move an app into a tool repository later, or absorb a tool into the binary, with no edit to the code that speaks the protocol.
docs/tool-protocol.md holds the contract. examples/echo-tool holds a tool to read end to end.
| Id | Name | What it shows |
|---|---|---|
home |
Home | Where a session opens: new, open, recent, tutorials |
files |
File Explorer | The project tree, and the verbs that change its shape |
viewer |
File Viewer | Open files, in tabs |
design |
Design Mode | A page you build, with click-to-capture for an agent |
tutorial |
Tutorials | Short walkthroughs of the product |
File Explorer and File Viewer are two apps over one Rust half. The machine has one filesystem, and apps/files.rs is the half that talks to it. Read the comment on the viewer registry row for the full argument.