Repolode
Submit
mengrru

mengrru/Spherse

A local-first desktop runtime where multiple AI agents share a project folder of files, run on schedules or events, and power interactive HTML apps.

View on GitHubWebsite
Stars
91
Forks
12
Open issues
21
Last commit
12 hours ago

What is it?

Spherse is a local runtime for running AI agents against a shared project directory. Plain files in the project serve as the user's data, and each agent can have its own system prompt, tool permissions, private and shared skills, MCP server connections, multiple persistent sessions, and chat themes. Sessions are stored in a SQLite database inside the project, and agent configuration uses Markdown, YAML, and JSON.

Automation is handled by triggers that run agents on a cron schedule or in response to custom events with payloads. Events can come from the user, an HTML page, or another agent. The built-in preview server serves HTML, images and other project files, and a UI SDK lets those pages read and write JSON data, create sessions, send messages to agents, and fire events.

The desktop app is built with Electron and React for macOS, Windows and Linux, and a token-protected web client lets mobile devices connect to the desktop runtime. The whole project folder can be copied or shared as a unit, including its data, agent configuration, skills, triggers and pages.

Key features

  • 01Multiple agents with separate prompts, tool permissions, skills and MCP connections in one project
  • 02Cron and custom-event triggers that run agents in new or existing sessions
  • 03Built-in HTML preview server with a UI SDK for reading data and driving agents
  • 04Local storage: plain files, Markdown/YAML/JSON config and SQLite sessions
  • 05Desktop apps for macOS, Windows and Linux, plus a token-protected mobile web client

Use cases

  • Running a persistent fictional world or interactive role-play with several characters
  • Building a personal record system with dashboards and scheduled daily summaries
  • Coordinating research, summarizing and archiving agents over a shared knowledge folder
  • Creating custom HTML tools that read local data and send requests to agents

Quick start

  1. 1

    Clone the repository

    git clone https://github.com/mengrru/Spherse.git
  2. 2

    Enter the project folder

    cd Spherse
  3. 3

    Install dependencies

    npm install
  4. 4

    Start the app in development mode

    npm run dev

Things to know

  • Local development requires Node.js 22.19 or newer.
  • You need an API key from a supported LLM provider before you can create agents.
  • The macOS release is not signed with an Apple Developer certificate, so macOS may show a warning on first launch.

In collections

Open-source AI agent frameworks & appsMCP serversPrivacy & local-first tools

Topics

#ai-agent#local-first#electron#typescript#automation#roleplay#worldbuilding#mcp#ai-roleplay#airp

FAQ

What is Spherse?
A local-first desktop runtime where multiple AI agents share a project folder of files, run on schedules or events, and power interactive HTML apps. Spherse is a local runtime for running AI agents against a shared project directory. Plain files in the project serve as the user's data, and each agent can have its own system prompt, tool permissions, private and shared skills, MCP server connections, multiple persistent sessions, and chat themes. Sessions are stored in a SQLite database inside the project, and agent configuration uses Markdown, YAML, and JSON.
Is Spherse free to use? What license does it have?
Spherse is open source under the MIT license. Check the license terms before using it in commercial products.
Is Spherse still maintained?
Actively maintained. The last commit to Spherse was on Oct 22, 2026.
What can I use Spherse for?
Running a persistent fictional world or interactive role-play with several characters Building a personal record system with dashboards and scheduled daily summaries Coordinating research, summarizing and archiving agents over a shared knowledge folder Creating custom HTML tools that read local data and send requests to agents
How do I install Spherse?
Clone the repository: git clone https://github.com/mengrru/Spherse.git Enter the project folder: cd Spherse Install dependencies: npm install Start the app in development mode: npm run dev
Where can I get Spherse?
The source code and installation instructions are on GitHub: https://github.com/mengrru/Spherse

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects