Limoni

Limoni is a local, read-only viewer for Ramune Project Task Graphs. It remembers validated Projects in a private per-user registry, restores the last selection, loads one trusted Project at a time, and serves the result through a loopback browser application.

Limoni does not create or edit Tasks, execute AI work, evaluate results, accept work, or write Project state. Those actions remain with the Agent Host, ramune.ai Skills, and Project Runtime.

The public npm package is a preview distribution. It does not represent a signed customer-production release.

Requirements

• Installation on macOS or Linux requires Node.js 22 or newer with npm.
• Windows setup installs the current Node.js LTS release for the current user when Node.js 22 or newer is unavailable.
• A trusted Ramune Project root containing _os/task_graph/*.task_graph.yaml when displaying Project data.

Install

Windows

Open Windows PowerShell normally—administrator access is not required—and run this one command:

irm https://raw.githubusercontent.com/huzaifanur/limoni-dev-public/main/scripts/install-windows.ps1 | iex

irm is the built-in alias for Invoke-RestMethod; it downloads the public setup script. iex is the alias for Invoke-Expression; it runs the downloaded script. Review the script before running the command if required by your security policy.

The setup verifies or installs Node.js 22+, installs limoni-dev@latest from npm, verifies the limoni CLI, and creates a Limoni shortcut in the current user's Start Menu. When needed, it downloads the official Node.js LTS ZIP, verifies its published SHA-256 digest, and installs it under the current user's Local AppData. It does not require administrator access, use an MSI, clone, or build the repository.

macOS and Linux

With Node.js 22 or newer installed, run:

npm install --global limoni-dev@latest && limoni --version

The npm package name is limoni-dev; the installed application command is limoni.

Development install from source

Contributors can build and install the current checkout:

cd /path/to/limoni-dev-public
npm ci
npm run install:local
limoni --version

npm ci installs the locked build dependencies. npm run install:local then:

1. Builds the Limoni frontend.
2. Creates a temporary npm package with npm pack.
3. Installs that package with npm install --global.
4. Deletes the temporary package.

limoni --version confirms the installed version. Every installation method produces one host-level limoni command that can open multiple compatible Projects. Installation does not add Limoni to a Project's package.json or change its lockfile.

Launch

From a trusted Project root:

cd /path/to/project
limoni

From another directory:

limoni --project-root /absolute/path/to/project

When a Project is supplied or detected, Limoni validates, remembers, selects, and prints its Project ID, Framework Contract, read mode, watch scope, and local URL. Otherwise it restores the last valid selection, falling back to the complete empty workspace. Keep the terminal process running while using Limoni.

The sidebar can add a Project through the native OS folder picker, select a remembered Project, or remove a registry entry. Removing an entry never deletes or changes Project files. Only the selected Project is loaded and watched; inactive Projects show Not loaded.

The registry contains only canonical roots, registration IDs, validated Project IDs/titles, and the last selection:

• Windows: %LOCALAPPDATA%\Limoni\projects.json
• macOS: ~/Library/Application Support/Limoni/projects.json
• Linux: ${XDG_CONFIG_HOME:-~/.config}/limoni/projects.json

Linux folder selection uses Zenity. If it is unavailable, install zenity or use limoni --project-root /absolute/path/to/project; the CLI route also remembers the Project.

CLI options

| Option | Purpose | Default | |---|---|---| | --project-root <path> | Project root to read | Current directory when it contains _os/task_graph; otherwise none | | --project-id <id> | Assert the discovered Project ID | No assertion | | --project-title <title> | Set the display-only title | Project ID | | --port <number> | Select a loopback port; 0 selects an available port | 4177 | | --no-open | Do not open the browser automatically | Browser open attempted | | --help | Print CLI usage | — | | --version | Print the installed version | — |

The Project ID always comes from the canonical Task Graph files. --project-id checks that value; it does not override it. --project-title affects display only.

Launch through Codex or Claude

Codex, Claude, or another coding Agent Host launches the same installed CLI:

limoni --project-root /absolute/path/to/project --port 0 --no-open

The host keeps the process running and reports the printed URL. The minimal launch-limoni Skill contains usage instructions only; installation and runtime behavior remain owned by Limoni.

Live refresh

While running, Limoni watches _os/task_graph and the parent directories of safe declared local file inputs and outputs.

• A valid change replaces the displayed model automatically.
• An invalid change keeps the previous valid model in memory, marks it stale, shows the reason, and retries until the Project becomes valid.
• No last-known-good Project model is saved to disk. Starting Limoni while the Project is invalid fails closed.

Stop

Press Ctrl+C in the terminal that launched Limoni. Closing the browser does not stop the process.

Update

On Windows, rerun the one-line PowerShell installation command. It installs the current limoni-dev@latest package and refreshes the existing shortcut.

On macOS or Linux, run:

npm install --global limoni-dev@latest && limoni --version

Stop existing Limoni processes before relying on the newly installed version.

Uninstall

npm uninstall --global limoni-dev

Windows users can also delete %APPDATA%\Microsoft\Windows\Start Menu\Programs\Limoni. Uninstalling Limoni does not remove or modify any Ramune Project. The small per-user Project registry remains until the user removes it explicitly.