# Geistr Core

> Reusable desktop-first AI app foundation built with Electron, React, and the Pi SDK.

- **Type:** MCP server
- **Install:** `agentstack add mcp-asm3r96-geistr-core`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Asm3r96](https://agentstack.voostack.com/s/asm3r96)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Asm3r96](https://github.com/Asm3r96)
- **Source:** https://github.com/Asm3r96/geistr-core
- **Website:** https://github.com/Asm3r96/geistr-core

## Install

```sh
agentstack add mcp-asm3r96-geistr-core
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Geistr Core

Geistr Core is a reusable desktop-first AI app foundation. You can run it as a polished local AI workspace today, or use it as the base layer for building your own agent app, research workspace, tutor, coding assistant, creative tool, or internal automation product.

The core idea is simple: the hard parts of a modern desktop agent app should already be done once — chat, sessions, providers, tools, permissions, memory, skills, MCP, background workflows, settings, packaging, and good UI rendering — so your next app can focus on its domain instead of rebuilding the foundation.

## Why I built this

I always have ideas for specific-use-case AI apps, and every time I started one I found myself rebuilding the same core pieces from scratch.

So I asked myself: **why don't I have a core app that already gives me the things I always need, so I can build on top of it?**

That is why I created Geistr Core for my own use: a base app I can reuse whenever I want to build a focused AI product. I am releasing it as open source for anyone who has a good idea and wants to build it without spending weeks recreating the foundation first.

Use this to save time, start closer to your real idea, and focus on the specific experience you want to create.

## What you get out of the box

- **Desktop app shell** — Electron + React app with chat, sidebar navigation, settings, themes, attachments, and packaged builds.
- **Pi SDK agent runtime** — Geistr wraps [Pi SDK / `@earendil-works/pi-coding-agent`](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) and [`@earendil-works/pi-ai`](https://www.npmjs.com/package/@earendil-works/pi-ai) instead of rebuilding agent/session/model infrastructure.
- **Many providers** — provider/model selection, thinking-level controls, API-key auth, and subscription/OAuth-style provider support where available.
- **Persistent local sessions** — SQLite-backed chat sessions, event history, attachments, and runtime context assembly.
- **Memory** — memory indexing, retrieval into prompts, read/write memory tools, and a Memory Galaxy graph UI.
- **Provider-independent web access** — built-in `web_search` and `web_fetch` tools exposed through Geistr names, not tied to the selected model provider.
- **Skills** — installed skill catalog, compact prompt listing, and read-only `skill_load` tool for loading full skill instructions on demand.
- **MCP servers** — STDIO and Streamable HTTP MCP support with controlled tool exposure.
- **Permission modes** — four app-level access modes: Read only, Request approval, Default, and Full access.
- **Rich chat rendering** — streaming assistant responses, thinking/tool activity visibility, approval cards, attachments, markdown rendering, and loop progress.
- **Background loops** — reusable workflow runtime for compaction, background tasks, validators, artifacts, retries, progress, and agent-triggered jobs.
- **Packaging flow** — local `electron-builder` packaging for desktop distribution experiments.

## The core architecture

Geistr Core separates reusable agent-app infrastructure from the app you build on top.

```txt
apps/desktop/              Electron + React desktop app
packages/core/             Reusable Geistr Core runtime and app systems
docs/                      Architecture, feature, and extension docs
.agents/skills/            Project workflow skills for agent-assisted development
scripts/                   Repo maintenance scripts
```

The desktop app owns UI, IPC, windows, local settings screens, and visual presentation. `packages/core` owns reusable systems: Pi SDK integration, provider/model selection, prompt assembly, tools, permissions, memory, skills, MCP, loops, artifacts, and persistence seams.

That gives you a practical split:

- build a new product by changing UI, prompts, skills, loops, and domain tools;
- keep the core runtime stable;
- avoid duplicating Pi SDK wiring in every screen;
- let agents read local docs and understand how to extend the app safely.

Start with the architecture docs:

- [`docs/architecture/architecture.md`](docs/architecture/architecture.md)
- [`docs/architecture/desktop-shell.md`](docs/architecture/desktop-shell.md)
- [`docs/core/core-agent-runtime.md`](docs/core/core-agent-runtime.md)
- [`docs/core/session-persistence.md`](docs/core/session-persistence.md)

## Stack

- **Runtime/package manager:** [Bun](https://bun.sh/)
- **Desktop:** [Electron](https://www.electronjs.org/)
- **Renderer:** [React](https://react.dev/) + TypeScript + Vite
- **Agent runtime:** [Pi SDK / `@earendil-works/pi-coding-agent`](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)
- **Model/provider layer:** [`@earendil-works/pi-ai`](https://www.npmjs.com/package/@earendil-works/pi-ai)
- **MCP:** [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk)
- **Local persistence:** SQLite-backed session storage
- **Packaging:** [electron-builder](https://www.electron.build/)
- **Tests:** Vitest + Testing Library

## Pi SDK relationship

Geistr Core uses Pi SDK as the foundation for sessions, models, auth, tools, context, and agent behavior. The app does not try to replace Pi. Instead, it wraps Pi behind stable Geistr seams so the desktop app can stay focused on product behavior and UI.

Useful docs:

- [`docs/roles/pi-sdk.md`](docs/roles/pi-sdk.md)
- [`docs/core/core-agent-runtime.md`](docs/core/core-agent-runtime.md)
- [`docs/core/provider-model-selection.md`](docs/core/provider-model-selection.md)
- [`docs/core/settings-provider-auth.md`](docs/core/settings-provider-auth.md)

## Memory

Geistr includes a local memory system for indexing useful session content, retrieving relevant memories into future prompts, and letting the agent read/write memories through controlled tools.

It also includes a read-only **Memory Galaxy** UI for exploring memories as a graph.

Docs:

- [`docs/loops/memory-tools.md`](docs/loops/memory-tools.md)
- [`docs/core/memory-galaxy.md`](docs/core/memory-galaxy.md)
- [`docs/core/session-persistence.md`](docs/core/session-persistence.md)

## Web search and fetch

Geistr includes provider-independent web tools:

- `web_search` — search the public web
- `web_fetch` — fetch and read a URL

These tools are exposed as Geistr tools and are not dependent on whichever model provider the user selects. The current adapter uses Exa MCP internally, but the agent sees stable Geistr tool names.

Docs:

- [`docs/core/web-tools.md`](docs/core/web-tools.md)
- [`docs/skills-mcp/mcp-servers.md`](docs/skills-mcp/mcp-servers.md)

## Skills and MCP

Skills give agents operational instructions without injecting every instruction into every prompt. The runtime lists active skills compactly, and the agent can call `skill_load` when it needs the full instructions.

MCP support lets the app expose external tools through STDIO or Streamable HTTP servers while still routing them through Geistr's permission and runtime model.

Docs:

- [`docs/skills-mcp/skills.md`](docs/skills-mcp/skills.md)
- [`docs/skills-mcp/mcp-servers.md`](docs/skills-mcp/mcp-servers.md)
- [`docs/roles/skills.md`](docs/roles/skills.md)
- [`docs/roles/tools.md`](docs/roles/tools.md)

## Permission modes

Geistr has four app-level permission modes:

| Mode | Behavior |
|---|---|
| Read only | Safe reads run automatically; mutation tools are unavailable or blocked. |
| Request approval | Safe reads run automatically; mutations ask through UI approval. |
| Default | Safe reads and low-risk internal changes run automatically; dangerous actions ask. |
| Full access | Most actions run without prompts; catastrophic blocked actions remain blocked. |

Docs:

- [`docs/core/tool-permissions.md`](docs/core/tool-permissions.md)

## Background loops

Geistr Core includes its own loop runtime for supervised background workflows.

A loop is a bounded workflow made from explicit steps: model nodes, deterministic code nodes, gates, validators, artifacts, retries, approvals, side effects, finalizers, and progress events. Loops can run automatically in the background or be exposed to the agent through the loop catalog so the agent can trigger them when useful.

The first real loop is session compaction: it runs after long sessions, summarizes context, stores artifacts, and wakes the same session with compact pending results.

The same pattern can power much more. For example, you can build a **deep search loop** with explicit steps:

1. clarify the research question;
2. search the web;
3. fetch promising sources;
4. extract claims and citations;
5. validate coverage;
6. write a structured report artifact;
7. notify the main chat when complete.

The main agent can then trigger `deep_search` from the loop catalog, keep chatting while it runs, and show progress in the background UI.

Docs:

- [`docs/loops/loop-runtime.md`](docs/loops/loop-runtime.md)
- [`docs/loops/loop-catalog.md`](docs/loops/loop-catalog.md)
- [`docs/loops/background-loop-runner.md`](docs/loops/background-loop-runner.md)
- [`docs/loops/artifact-store.md`](docs/loops/artifact-store.md)
- [`docs/loops/session-compaction-loop.md`](docs/loops/session-compaction-loop.md)

## Roadmap

High-level core improvements planned next:

- [ ] Add token usage statistics by model and day, split by input and output tokens
- [ ] Add a user profile screen
- [ ] Add automatic update notifications with a download prompt when a new version is released
- [ ] Improve memory injection into the runtime
- [ ] Improve session management
- [ ] Add optional downloadable voice input using a small open-source model

## Download and install

For normal use, download the latest installer from [GitHub Releases](https://github.com/Asm3r96/geistr-core/releases/latest):

- **Windows:** download `Geistr Core Setup 1.0.0.exe`
- **macOS Apple Silicon:** download `Geistr Core-1.0.0-arm64.dmg`
- **Linux:** download the `.AppImage` file

> First public builds are unsigned. Windows SmartScreen or macOS Gatekeeper may show warnings until signing and notarization are added.

If you want to modify Geistr Core or build an app on top of it, use the source workflow below.

## Run locally from source

Install dependencies:

```bash
bun install
```

Run validation:

```bash
bun run typecheck
bun run test
```

Run the desktop app in development:

```bash
cd apps/desktop
bun run dev
```

Build the desktop app:

```bash
cd apps/desktop
bun run build
```

Create a local packaged desktop directory:

```bash
bun run package:desktop:dir
```

Packaging docs:

- [`docs/release/desktop-packaging.md`](docs/release/desktop-packaging.md)

## Release process

This repo includes GitHub Actions for CI and tag-based releases.

- CI runs on pushes and pull requests to `main`.
- Release builds run when a tag like `v1.0.0` is pushed.
- Release artifacts are uploaded to GitHub Releases.

To publish a release after pushing the repo:

```bash
git tag v1.0.0
git push origin v1.0.0
```

Docs/files:

- [`CHANGELOG.md`](CHANGELOG.md)
- [`RELEASE_NOTES.md`](RELEASE_NOTES.md)
- [`.github/workflows/ci.yml`](.github/workflows/ci.yml)
- [`.github/workflows/release.yml`](.github/workflows/release.yml)

## Build on top

Good extension points:

- add domain-specific prompts and profile defaults;
- add tools behind Geistr permission tiers;
- add skills for repeatable agent workflows;
- add MCP servers for external systems;
- add loops for long-running background jobs;
- add app-specific screens on top of the desktop shell;
- replace or extend provider/auth configuration;
- customize memory indexing and retrieval behavior.

Recommended docs before extending:

- [`docs/README.md`](docs/README.md)
- [`docs/roles/core.md`](docs/roles/core.md)
- [`docs/roles/apps.md`](docs/roles/apps.md)
- [`docs/roles/development-workflow.md`](docs/roles/development-workflow.md)
- [`docs/roles/code-quality.md`](docs/roles/code-quality.md)

## Repository status

This repository is intended to be the public reusable core foundation. It should not include product-specific behavior. Build product-specific apps on top of it instead of mixing them into the core layer.

## License

MIT

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Asm3r96](https://github.com/Asm3r96)
- **Source:** [Asm3r96/geistr-core](https://github.com/Asm3r96/geistr-core)
- **License:** MIT
- **Homepage:** https://github.com/Asm3r96/geistr-core

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-asm3r96-geistr-core
- Seller: https://agentstack.voostack.com/s/asm3r96
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.