kluris 0.1.0__tar.gz

kluris-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest tests/ -v --cov=kluris --cov-report=term-missing

kluris-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,19 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install hatch
+      - run: hatch build
+      - uses: pypa/gh-action-pypi-publish@release/v1

kluris-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+.coverage
+.pytest_cache/
+.idea/
+.DS_Store
+Thumbs.db
+*.egg

kluris-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gabriel Voicu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kluris-0.1.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: kluris
+Version: 0.1.0
+Summary: Create and manage git-backed AI brains for multi-project, multi-agent teams
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-frontmatter>=1.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Kluris
+
+> Create and manage git-backed AI brains for multi-project, multi-agent teams.
+
+*When your best engineer sleeps, Kluris doesn't. When they leave, Kluris stays.*
+
+## What is Kluris?
+
+Kluris is a CLI tool that creates **brains** — standalone git repos of
+structured markdown that AI coding agents read, search, and update through
+globally installed slash commands.
+
+**Kluris = the tool. A brain = the git repo it creates.**
+
+### Why not a wiki, Notion, or CLAUDE.md?
+
+- **Wikis and Notion** are for humans. Agents can't natively read them, search
+  across them, or write back. Kluris brains are markdown in git — AI-native.
+- **CLAUDE.md** is per-project and per-tool. A brain sits above all your
+  projects and works with 8 different AI agents simultaneously.
+- **Agent memory** is session-scoped and ephemeral. A brain is persistent,
+  version-controlled, and shared across the entire team.
+
+One brain serves all your projects. Every AI agent on the team reads the same
+knowledge. When someone leaves, nothing is lost.
+
+## Quick start
+
+```bash
+pipx install kluris
+kluris doctor                          # Check prerequisites
+kluris create ~/my-brain --type team   # Create a team brain
+```
+
+Then open any project and run `/kluris.learn` — the AI agent will analyze
+your codebase and populate the brain with architecture, conventions, APIs,
+and decisions.
+
+### Example workflow
+
+```bash
+# 1. Create a brain for your team
+kluris create ~/acme-brain --type team
+
+# 2. In your backend project, run the slash command:
+#    /kluris.learn focus on architecture and API design
+
+# 3. In your frontend project:
+#    /kluris.learn focus on components and state management
+
+# 4. Now any agent in any project can use the brain:
+#    /kluris.think implement the new auth flow
+#    (agent loads architecture decisions, API contracts, conventions from the brain)
+
+# 5. After a session with useful decisions:
+#    /kluris.remember
+
+# 6. Validate and push
+kluris dream                           # Regenerate indexes, check links
+kluris push                            # Commit and push to git
+
+# 7. Visualize the brain
+kluris mri                             # Opens brain-mri.html
+```
+
+## What a brain looks like
+
+```
+acme-brain/
+├── kluris.yml              # Brain config
+├── brain.md                # Root index (auto-generated)
+├── index.md                # Flat neuron list (auto-generated)
+├── glossary.md             # Domain terms (hand-edited)
+├── README.md               # Usage guide
+├── architecture/
+│   ├── map.md              # Lobe index (auto-generated)
+│   ├── auth-keycloak.md    # <- neuron
+│   └── data-flow.md        # <- neuron
+├── decisions/
+│   ├── map.md
+│   └── use-raw-sql.md      # <- neuron (decision template)
+├── services/
+│   ├── map.md
+│   └── btb-backend/
+│       ├── map.md
+│       ├── endpoints/
+│       │   └── ...
+│       └── data-model.md
+└── ...
+```
+
+Folders are **lobes** (knowledge regions). Files are **neurons** (knowledge
+units). Links between neurons are **synapses**. Auto-generated `map.md` files
+keep everything navigable.
+
+## Brain types
+
+| Type | Lobes | Use case |
+|------|-------|----------|
+| `team` (default) | architecture, decisions, product, standards, services, infrastructure, cortex, wisdom | Shared team knowledge across projects |
+| `personal` | projects, tasks, releases, notes | Individual developer brain |
+| `product` | prd, features, ux, analytics, competitors, decisions | Product management |
+| `research` | literature, experiments, findings, datasets, tools, questions | Research projects |
+| `blank` | (empty) | Custom structure |
+
+```bash
+kluris create ~/my-brain --type personal
+kluris create ~/product-brain --type product
+```
+
+## How it works
+
+1. `kluris create` scaffolds a git repo with lobes, indexes, and a glossary
+2. `kluris install` generates slash commands for 8 AI agents
+3. Agents use `/kluris.learn` to scan projects and populate the brain
+4. Team members use `/kluris.think <task>` to load brain context before working
+5. `kluris dream` validates links, detects orphans, regenerates indexes
+6. `kluris mri` generates an interactive HTML graph of the brain
+
+## Slash commands (used inside AI agents)
+
+| Command | What it does |
+|---------|-------------|
+| `/kluris <anything>` | **Main command.** Natural language. |
+| `/kluris.think <task>` | Load brain context, work as team expert. |
+| `/kluris.remember [topic]` | Extract knowledge from session. |
+| `/kluris.learn [focus]` | Deep-scan project, populate brain. |
+| `/kluris.recall <topic>` | Search the brain. |
+| `/kluris.neuron <topic>` | Create a knowledge file. |
+| `/kluris.lobe <name>` | Create a knowledge region. |
+| `/kluris.push [msg]` | Commit and push to git. |
+| `/kluris.dream [focus]` | AI-powered brain maintenance. |
+
+## CLI commands
+
+| Command | Flags | What it does |
+|---------|-------|-------------|
+| `kluris create <path>` | `--type`, `--from-config`, `--json` | Create a new brain |
+| `kluris clone <url> [path]` | `--json` | Clone an existing brain |
+| `kluris list` | `--json` | List all registered brains |
+| `kluris status` | `--brain`, `--json` | Brain tree and recent changes |
+| `kluris recall <query>` | `--brain`, `--json` | Search across neurons |
+| `kluris neuron <path>` | `--lobe`, `--template`, `--brain`, `--json` | Create a neuron |
+| `kluris lobe <name>` | `--parent`, `--description`, `--brain`, `--json` | Create a lobe |
+| `kluris dream` | `--brain`, `--json` | Regenerate maps, validate links |
+| `kluris push` | `--message`, `--brain`, `--json` | Commit and push |
+| `kluris mri` | `--brain`, `--output`, `--json` | Generate brain visualization |
+| `kluris install` | `--json` | Install slash commands for agents |
+| `kluris remove <name>` | `--json` | Unregister a brain |
+| `kluris doctor` | `--json` | Check prerequisites |
+| `kluris help [command]` | `--json` | Show help |
+
+All commands support `--json` for machine-readable output.
+
+## Neuron templates
+
+The `team` brain type includes templates for structured knowledge:
+
+```bash
+kluris neuron auth-migration.md --lobe decisions --template decision
+```
+
+| Template | Sections |
+|----------|----------|
+| `decision` | Context, Decision, Rationale, Alternatives considered, Consequences |
+| `incident` | Summary, Timeline, Root cause, Impact, Resolution, Lessons learned |
+| `runbook` | Purpose, Prerequisites, Steps, Rollback, Contacts |
+
+## Brain vocabulary
+
+| Term | Meaning |
+|------|---------|
+| **Brain** | Git repo of structured markdown |
+| **Lobe** | Folder / knowledge region |
+| **Neuron** | Single knowledge file |
+| **Synapse** | Link between neurons (bidirectional) |
+| **Map** | Auto-generated lobe index |
+| **Index** | Flat list of all neurons |
+| **MRI** | Interactive brain visualization |
+| **Dream** | Brain maintenance — validate, repair |
+
+## Supported agents
+
+Claude Code, Cursor, Windsurf, GitHub Copilot, Codex, Gemini CLI, Kilo Code,
+Junie
+
+## License
+
+MIT

kluris-0.1.0/README.md

@@ -0,0 +1,189 @@
+# Kluris
+
+> Create and manage git-backed AI brains for multi-project, multi-agent teams.
+
+*When your best engineer sleeps, Kluris doesn't. When they leave, Kluris stays.*
+
+## What is Kluris?
+
+Kluris is a CLI tool that creates **brains** — standalone git repos of
+structured markdown that AI coding agents read, search, and update through
+globally installed slash commands.
+
+**Kluris = the tool. A brain = the git repo it creates.**
+
+### Why not a wiki, Notion, or CLAUDE.md?
+
+- **Wikis and Notion** are for humans. Agents can't natively read them, search
+  across them, or write back. Kluris brains are markdown in git — AI-native.
+- **CLAUDE.md** is per-project and per-tool. A brain sits above all your
+  projects and works with 8 different AI agents simultaneously.
+- **Agent memory** is session-scoped and ephemeral. A brain is persistent,
+  version-controlled, and shared across the entire team.
+
+One brain serves all your projects. Every AI agent on the team reads the same
+knowledge. When someone leaves, nothing is lost.
+
+## Quick start
+
+```bash
+pipx install kluris
+kluris doctor                          # Check prerequisites
+kluris create ~/my-brain --type team   # Create a team brain
+```
+
+Then open any project and run `/kluris.learn` — the AI agent will analyze
+your codebase and populate the brain with architecture, conventions, APIs,
+and decisions.
+
+### Example workflow
+
+```bash
+# 1. Create a brain for your team
+kluris create ~/acme-brain --type team
+
+# 2. In your backend project, run the slash command:
+#    /kluris.learn focus on architecture and API design
+
+# 3. In your frontend project:
+#    /kluris.learn focus on components and state management
+
+# 4. Now any agent in any project can use the brain:
+#    /kluris.think implement the new auth flow
+#    (agent loads architecture decisions, API contracts, conventions from the brain)
+
+# 5. After a session with useful decisions:
+#    /kluris.remember
+
+# 6. Validate and push
+kluris dream                           # Regenerate indexes, check links
+kluris push                            # Commit and push to git
+
+# 7. Visualize the brain
+kluris mri                             # Opens brain-mri.html
+```
+
+## What a brain looks like
+
+```
+acme-brain/
+├── kluris.yml              # Brain config
+├── brain.md                # Root index (auto-generated)
+├── index.md                # Flat neuron list (auto-generated)
+├── glossary.md             # Domain terms (hand-edited)
+├── README.md               # Usage guide
+├── architecture/
+│   ├── map.md              # Lobe index (auto-generated)
+│   ├── auth-keycloak.md    # <- neuron
+│   └── data-flow.md        # <- neuron
+├── decisions/
+│   ├── map.md
+│   └── use-raw-sql.md      # <- neuron (decision template)
+├── services/
+│   ├── map.md
+│   └── btb-backend/
+│       ├── map.md
+│       ├── endpoints/
+│       │   └── ...
+│       └── data-model.md
+└── ...
+```
+
+Folders are **lobes** (knowledge regions). Files are **neurons** (knowledge
+units). Links between neurons are **synapses**. Auto-generated `map.md` files
+keep everything navigable.
+
+## Brain types
+
+| Type | Lobes | Use case |
+|------|-------|----------|
+| `team` (default) | architecture, decisions, product, standards, services, infrastructure, cortex, wisdom | Shared team knowledge across projects |
+| `personal` | projects, tasks, releases, notes | Individual developer brain |
+| `product` | prd, features, ux, analytics, competitors, decisions | Product management |
+| `research` | literature, experiments, findings, datasets, tools, questions | Research projects |
+| `blank` | (empty) | Custom structure |
+
+```bash
+kluris create ~/my-brain --type personal
+kluris create ~/product-brain --type product
+```
+
+## How it works
+
+1. `kluris create` scaffolds a git repo with lobes, indexes, and a glossary
+2. `kluris install` generates slash commands for 8 AI agents
+3. Agents use `/kluris.learn` to scan projects and populate the brain
+4. Team members use `/kluris.think <task>` to load brain context before working
+5. `kluris dream` validates links, detects orphans, regenerates indexes
+6. `kluris mri` generates an interactive HTML graph of the brain
+
+## Slash commands (used inside AI agents)
+
+| Command | What it does |
+|---------|-------------|
+| `/kluris <anything>` | **Main command.** Natural language. |
+| `/kluris.think <task>` | Load brain context, work as team expert. |
+| `/kluris.remember [topic]` | Extract knowledge from session. |
+| `/kluris.learn [focus]` | Deep-scan project, populate brain. |
+| `/kluris.recall <topic>` | Search the brain. |
+| `/kluris.neuron <topic>` | Create a knowledge file. |
+| `/kluris.lobe <name>` | Create a knowledge region. |
+| `/kluris.push [msg]` | Commit and push to git. |
+| `/kluris.dream [focus]` | AI-powered brain maintenance. |
+
+## CLI commands
+
+| Command | Flags | What it does |
+|---------|-------|-------------|
+| `kluris create <path>` | `--type`, `--from-config`, `--json` | Create a new brain |
+| `kluris clone <url> [path]` | `--json` | Clone an existing brain |
+| `kluris list` | `--json` | List all registered brains |
+| `kluris status` | `--brain`, `--json` | Brain tree and recent changes |
+| `kluris recall <query>` | `--brain`, `--json` | Search across neurons |
+| `kluris neuron <path>` | `--lobe`, `--template`, `--brain`, `--json` | Create a neuron |
+| `kluris lobe <name>` | `--parent`, `--description`, `--brain`, `--json` | Create a lobe |
+| `kluris dream` | `--brain`, `--json` | Regenerate maps, validate links |
+| `kluris push` | `--message`, `--brain`, `--json` | Commit and push |
+| `kluris mri` | `--brain`, `--output`, `--json` | Generate brain visualization |
+| `kluris install` | `--json` | Install slash commands for agents |
+| `kluris remove <name>` | `--json` | Unregister a brain |
+| `kluris doctor` | `--json` | Check prerequisites |
+| `kluris help [command]` | `--json` | Show help |
+
+All commands support `--json` for machine-readable output.
+
+## Neuron templates
+
+The `team` brain type includes templates for structured knowledge:
+
+```bash
+kluris neuron auth-migration.md --lobe decisions --template decision
+```
+
+| Template | Sections |
+|----------|----------|
+| `decision` | Context, Decision, Rationale, Alternatives considered, Consequences |
+| `incident` | Summary, Timeline, Root cause, Impact, Resolution, Lessons learned |
+| `runbook` | Purpose, Prerequisites, Steps, Rollback, Contacts |
+
+## Brain vocabulary
+
+| Term | Meaning |
+|------|---------|
+| **Brain** | Git repo of structured markdown |
+| **Lobe** | Folder / knowledge region |
+| **Neuron** | Single knowledge file |
+| **Synapse** | Link between neurons (bidirectional) |
+| **Map** | Auto-generated lobe index |
+| **Index** | Flat list of all neurons |
+| **MRI** | Interactive brain visualization |
+| **Dream** | Brain maintenance — validate, repair |
+
+## Supported agents
+
+Claude Code, Cursor, Windsurf, GitHub Copilot, Codex, Gemini CLI, Kilo Code,
+Junie
+
+## License
+
+MIT

kluris-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kluris"
+version = "0.1.0"
+description = "Create and manage git-backed AI brains for multi-project, multi-agent teams"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = [
+    "click>=8.1",
+    "rich>=13.0",
+    "pyyaml>=6.0",
+    "python-frontmatter>=1.1",
+    "pydantic>=2.0",
+]
+
+[project.scripts]
+kluris = "kluris.cli:cli"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-cov>=5.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kluris"]

kluris-0.1.0/src/kluris/__init__.py

@@ -0,0 +1,3 @@
+"""Kluris — Git-backed AI brain manager."""
+
+__version__ = "0.1.0"