Grimoire keeps its own SECRET_KEY, docker-compose.yml is the deploy compose, a repo rename moves its snippets; logo, README, licence #214
@@ -1,42 +1,111 @@
|
||||
# Fabled Grimoire
|
||||
<p align="center">
|
||||
<img src="frontend/public/favicon.svg" width="96" alt="">
|
||||
</p>
|
||||
|
||||
A self-hosted work system-of-record for software projects, built to be driven by Claude Code. Notes, tasks, issues, projects, milestones, rules, and stored processes — reachable from Claude via a built-in MCP endpoint and a bundled Claude Code plugin, with a clean web UI for humans. No in-app LLM; Claude is the sole assistant.
|
||||
<h1 align="center">Fabled Grimoire</h1>
|
||||
|
||||
## Features
|
||||
<p align="center">A self-hosted system of record for the work you do with Claude Code.</p>
|
||||
|
||||
Notes, tasks and issues; projects with milestones as plans; rules that reach Claude when its work matches them or at a moment of work; lessons, snippets of prior art and a ledger of the code they account for; design systems; ideas shared across projects on the same platform; and stored processes. Semantic search feeds both Claude's recall and the plugin's context injection. A knowledge graph, sharing with users and groups, and scheduled backups round it out. See [Features](docs/features.md).
|
||||
Claude records what it learned, decided and built in Grimoire, and that record reaches the next session, so a solution is recalled instead of reinvented. Notes, tasks, plans, rules, lessons and reusable code live in one place. Claude reaches them through a built-in MCP endpoint and the bundled Claude Code plugin, and people read and edit the same records in the web UI. There is no language model inside Grimoire: Claude is the only assistant.
|
||||
|
||||
## Quick Start
|
||||
## Quick start
|
||||
|
||||
**Prerequisites:** Docker and Docker Compose. No GPU or local model needed — Claude is the sole assistant, reached over MCP.
|
||||
|
||||
Download [`docker-compose.quickstart.yml`](docker-compose.quickstart.yml) from this repo, then:
|
||||
You need Docker with Compose. Download [`docker-compose.quickstart.yml`](docker-compose.quickstart.yml), then:
|
||||
|
||||
```bash
|
||||
# Optional but recommended — set a secret key
|
||||
export SECRET_KEY=your-random-secret-here
|
||||
SECRET_KEY=$(python3 -c 'import secrets; print(secrets.token_hex(32))') \
|
||||
docker compose -f docker-compose.quickstart.yml up -d
|
||||
```
|
||||
|
||||
Open `http://localhost:5000`. The first account you register becomes the admin.
|
||||
|
||||
To connect Claude, create an API key under **Settings → MCP Access**, then in Claude Code:
|
||||
|
||||
```
|
||||
/plugin marketplace add https://git.fabledsword.com/bvandeusen/FabledGrimoire.git
|
||||
/plugin install grimoire@grimoire-plugin
|
||||
```
|
||||
|
||||
The plugin asks for your Grimoire URL and the API key. Settings → MCP Access shows the exact commands for your instance.
|
||||
|
||||
## Configuration
|
||||
|
||||
Set these in the environment or a `.env` file beside the compose file:
|
||||
|
||||
| Variable | Needed | What it does |
|
||||
|----------|--------|--------------|
|
||||
| `SECRET_KEY` | Yes | Signs sessions and seals stored credentials. Set it once and keep it |
|
||||
| `BASE_URL` | Behind a proxy | The public URL, used in email links and SSO redirects |
|
||||
| `SECURE_COOKIES` | Over HTTPS | `true` when Grimoire is served over HTTPS |
|
||||
| `TRUST_PROXY_HEADERS` | Behind a proxy | `true` to read the client address from the proxy's headers |
|
||||
| `POSTGRES_PASSWORD` | Recommended | The database password (defaults to `grimoire`) |
|
||||
|
||||
Everything else (registration, email, SSO, git forge connections, retrieval tuning, backups) is in **Settings**, or listed in [Configuration](docs/configuration.md).
|
||||
|
||||
## Setup pitfalls
|
||||
|
||||
- **Keep your `SECRET_KEY`.** Forge tokens and the backup bucket's secret are sealed under it. If it changes, Settings asks you to enter those credentials again.
|
||||
- **The embedding model downloads on first use**, into the `/data` volume. Without internet access, semantic search falls back to keyword search until the model is in place.
|
||||
- **Behind a reverse proxy, turn off response buffering** for `/mcp`, because MCP responses stream. [Configuration](docs/configuration.md#behind-a-reverse-proxy) has an Nginx example.
|
||||
|
||||
## Updating and backups
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.quickstart.yml pull
|
||||
docker compose -f docker-compose.quickstart.yml up -d
|
||||
```
|
||||
|
||||
Open `http://localhost:5000`. The first user to register becomes admin. To connect Claude, create an API key under **Settings → MCP Access** and install the Claude Code plugin — see [API Keys & MCP](docs/api-keys-and-mcp.md).
|
||||
Database migrations run when the app starts. Claude Code updates the plugin from its marketplace; run `/reload-plugins` after an update.
|
||||
|
||||
> **Development:** To build from source, see [Development](docs/development.md).
|
||||
Everything Grimoire stores is in the database. **Settings → Data → Scheduled backups** writes a daily backup to a folder or an S3-compatible bucket, and `python -m grimoire.restore` brings a fresh instance back from one. See [Backups](docs/backups.md).
|
||||
|
||||
## Documentation
|
||||
## Features
|
||||
|
||||
| Doc | Contents |
|
||||
|-----|----------|
|
||||
| [Architecture](docs/architecture.md) | Stack, design decisions, data models, key services |
|
||||
| [Configuration](docs/configuration.md) | Environment variables, Docker Compose, production setup, security |
|
||||
| [Features](docs/features.md) | Detailed feature breakdown and keyboard shortcuts |
|
||||
| [Development](docs/development.md) | Dev workflow, CI/CD, migrations, release process |
|
||||
| [API Keys & MCP](docs/api-keys-and-mcp.md) | API keys and installing the Claude Code plugin |
|
||||
| [SSO / OAuth](docs/sso-oauth.md) | OIDC setup for Authentik, Keycloak, and other providers |
|
||||
| [Backups](docs/backups.md) | Scheduled backups to a folder or S3, and restoring from one |
|
||||
| [Design system](docs/design-system.md) | The FabledSword house style and how Grimoire applies it |
|
||||
| [API Reference](docs/api-reference.md) | All REST API endpoints |
|
||||
**Working with Claude**
|
||||
- Claude enters a project and gets a short primer: its goal, current plans, open tasks and areas.
|
||||
- Your rules reach Claude when its work matches them, or at a moment of work such as finishing a task or pushing code.
|
||||
- Before Claude writes a file or runs a command, the plugin shows it the rules, lessons and reusable code that may apply.
|
||||
- Stored procedures, such as a drift audit, become Claude Code skills.
|
||||
|
||||
## License
|
||||
**Recording the work**
|
||||
- Notes in a Markdown editor, with wikilinks, tags and version history.
|
||||
- Tasks, issues and time-boxed investigations, with work logs that the next session reads first.
|
||||
- Plans as milestones: a design plus ordered steps.
|
||||
- Lessons learned the hard way, linked to the rules they illustrate.
|
||||
- Duplicate checks, so a new record that matches an existing one updates it instead.
|
||||
|
||||
This project is privately maintained.
|
||||
**Reusing code**
|
||||
- Snippets of reusable code, each with when to reach for it and where it lives in the repo.
|
||||
- With a git forge connected, Grimoire tracks every function and style in your repos and shows which ones are still unaccounted for.
|
||||
- Ideas shared across projects on the same platform, with each project's answer recorded.
|
||||
- Design systems with tokens, inheritance and a generated stylesheet.
|
||||
|
||||
**For people**
|
||||
- A web UI to browse, search and edit everything, plus a graph of how notes connect.
|
||||
- Sharing with users and groups, as viewer, editor or admin.
|
||||
- Email and password sign-in, optional SSO through OIDC, and invite links.
|
||||
- Personal export to Markdown or JSON, and admin backup and restore.
|
||||
|
||||
The full list is in [Features](docs/features.md).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| What you see | Why | Fix |
|
||||
|--------------|-----|-----|
|
||||
| `SECRET_KEY is set to the insecure default` at startup | `SECURE_COOKIES=true` while `SECRET_KEY` is still the built-in default | Set `SECRET_KEY` |
|
||||
| `Can't locate revision identified by '…'` at startup | An older image is running against a database a newer one has already migrated | Run the newer image; migrations only move forward |
|
||||
| The plugin's tools are missing in Claude Code | The plugin isn't installed, or Claude Code hasn't reloaded it | `/plugin` to install or update it, then `/reload-plugins` |
|
||||
| Search finds only exact words | The embedding model hasn't downloaded yet | Give the app internet access once, or wait for the first download to finish |
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
cp .env.example .env # then set SECRET_KEY
|
||||
docker compose up --build
|
||||
```
|
||||
|
||||
[Development](docs/development.md) covers checks, migrations, the plugin and CI. [Architecture](docs/architecture.md) describes how it is built, and the [API reference](docs/api-reference.md) lists every REST endpoint.
|
||||
|
||||
## Licence
|
||||
|
||||
Fabled Grimoire is privately maintained. All rights reserved.
|
||||
|
||||
@@ -3,6 +3,8 @@ defineProps<{ size?: number }>();
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<!-- The clasped grimoire, the same drawing as public/favicon.svg. Its colours
|
||||
are the mark's own and stay fixed in both themes, like the tab icon. -->
|
||||
<svg
|
||||
class="app-logo"
|
||||
xmlns="http://www.w3.org/2000/svg"
|
||||
@@ -11,45 +13,21 @@ defineProps<{ size?: number }>();
|
||||
:height="size ?? 24"
|
||||
aria-hidden="true"
|
||||
>
|
||||
<defs>
|
||||
<linearGradient id="logo-gradient" x1="0" y1="0" x2="1" y2="1">
|
||||
<stop offset="0%" stop-color="var(--fs-accent)" />
|
||||
<stop offset="100%" stop-color="var(--fs-accent-deep)" />
|
||||
</linearGradient>
|
||||
</defs>
|
||||
<!-- Book body -->
|
||||
<path class="logo-book" d="M4 7 C4 7 8 5 16 6 C24 5 28 7 28 7 L28 26 C28 26 24 24 16 25 C8 24 4 26 4 26 Z" stroke-width="0.5"/>
|
||||
<!-- Book spine -->
|
||||
<line class="logo-spine" x1="16" y1="6" x2="16" y2="25" stroke-width="0.8"/>
|
||||
<!-- Left page lines -->
|
||||
<line class="logo-lines" x1="7" y1="11" x2="14" y2="10.5" stroke-width="0.6" stroke-linecap="round"/>
|
||||
<line class="logo-lines" x1="7" y1="14" x2="14" y2="13.5" stroke-width="0.6" stroke-linecap="round"/>
|
||||
<line class="logo-lines" x1="7" y1="17" x2="14" y2="16.5" stroke-width="0.6" stroke-linecap="round"/>
|
||||
<line class="logo-lines" x1="7" y1="20" x2="12" y2="19.5" stroke-width="0.6" stroke-linecap="round"/>
|
||||
<!-- Right page lines -->
|
||||
<line class="logo-lines" x1="18" y1="10.5" x2="25" y2="11" stroke-width="0.6" stroke-linecap="round"/>
|
||||
<line class="logo-lines" x1="18" y1="13.5" x2="25" y2="14" stroke-width="0.6" stroke-linecap="round"/>
|
||||
<line class="logo-lines" x1="18" y1="16.5" x2="25" y2="17" stroke-width="0.6" stroke-linecap="round"/>
|
||||
<!-- Magic spark -->
|
||||
<g transform="translate(24, 5)">
|
||||
<path d="M0 -4 L1 -1 L4 0 L1 1 L0 4 L-1 1 L-4 0 L-1 -1 Z" fill="#f6ad55"/>
|
||||
<path d="M0 -2.5 L0.6 -0.6 L2.5 0 L0.6 0.6 L0 2.5 L-0.6 0.6 L-2.5 0 L-0.6 -0.6 Z" fill="#fbd38d"/>
|
||||
</g>
|
||||
<!-- Secondary sparkles -->
|
||||
<circle cx="20" cy="3" r="0.7" fill="#f6ad55" opacity="0.7"/>
|
||||
<circle cx="27" cy="8" r="0.5" fill="#fbd38d" opacity="0.6"/>
|
||||
<!-- page block, seen at the fore-edge -->
|
||||
<path d="M8.5 4.5 H25.5 Q27 4.5 27 6 V27 Q27 28.5 25.5 28.5 H8.5 Z" fill="#E9DFC6"/>
|
||||
<path d="M25 7 V26.5" stroke="#C9BB97" stroke-width="0.6"/>
|
||||
<!-- cover -->
|
||||
<path d="M5 4 Q5 3 6 3 H24 Q25.5 3 25.5 4.5 V26.5 Q25.5 28 24 28 H6 Q5 28 5 27 Z" fill="#5B4A8A"/>
|
||||
<!-- spine band -->
|
||||
<rect x="5" y="3" width="3.2" height="25" rx="0.6" fill="#47396E"/>
|
||||
<!-- corner fittings -->
|
||||
<path d="M21.5 3 H24 Q25.5 3 25.5 4.5 V7 Z" fill="#D4A94E"/>
|
||||
<path d="M21.5 28 H24 Q25.5 28 25.5 26.5 V24 Z" fill="#D4A94E"/>
|
||||
<!-- clasp across the fore-edge -->
|
||||
<rect x="22.5" y="14" width="5.5" height="3.6" rx="0.8" fill="#D4A94E"/>
|
||||
<circle cx="26.4" cy="15.8" r="0.7" fill="#8A6A22"/>
|
||||
<!-- sigil: a four-pointed star in a ring -->
|
||||
<circle cx="15.5" cy="15.5" r="5.2" fill="none" stroke="#D4A94E" stroke-width="0.9"/>
|
||||
<path d="M15.5 11.4 L16.5 14.5 L19.6 15.5 L16.5 16.5 L15.5 19.6 L14.5 16.5 L11.4 15.5 L14.5 14.5 Z" fill="#F1D48A"/>
|
||||
</svg>
|
||||
</template>
|
||||
|
||||
<style scoped>
|
||||
.logo-book {
|
||||
fill: url(#logo-gradient);
|
||||
stroke: color-mix(in srgb, var(--fs-accent) 70%, transparent);
|
||||
}
|
||||
.logo-spine {
|
||||
stroke: var(--fs-text-secondary);
|
||||
}
|
||||
.logo-lines {
|
||||
stroke: var(--fs-text-tertiary);
|
||||
}
|
||||
</style>
|
||||
|
||||
Reference in New Issue
Block a user