crowd-control 0.0.1__tar.gz

crowd_control-0.0.1/.claude/settings.local.json

@@ -0,0 +1,18 @@
+{
+  "permissions": {
+    "allow": [
+      "WebSearch",
+      "WebFetch(domain:modelcontextprotocol.github.io)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:py.sdk.modelcontextprotocol.io)",
+      "WebFetch(domain:realpython.com)",
+      "WebFetch(domain:scrapfly.io)",
+      "mcp__context7__resolve-library-id",
+      "mcp__context7__query-docs",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "WebFetch(domain:api.github.com)"
+    ]
+  },
+  "outputStyle": "Explanatory",
+  "prefersReducedMotion": true
+}

crowd_control-0.0.1/.claude/skills/create-plan/SKILL.md

@@ -0,0 +1,24 @@
+# Create Plan Skill
+
+## Purpose
+
+Create a new plan for work. This includes planning for any kind of work that creates or updates non-plan files.
+
+## Invocation
+
+User or agent invokes `/create-plan description-of-plan`.
+
+## Request
+
+Consider any relevant history when this skill is invoked. Often the user will want you to create a plan from some
+recent discovery work. This is initial planning work, so keep things high level and details will be broken down later.
+
+## Steps
+
+1. Create the plan.
+2. Only after the plan is complete, invoke the `/review-plan` skill on the plan.
+
+## Rules
+
+- Write the details in a new file in the `docs/plans/` directory.
+- Consult the user to resolve any ambiguity in decision-making.

crowd_control-0.0.1/.claude/skills/detail-plan/SKILL.md

@@ -0,0 +1,32 @@
+# Detail Plan Skill
+
+## Purpose
+
+Break down a plan into much more detail so the user can ensure implementation aligns with their expectations. Also to
+produce a plan that can be easily followed without any room for ambiguity.
+
+## Invocation
+
+User invokes `/detail-plan description`.
+
+## Request
+
+Break down the planning referenced by the user-provided description into very high detail.
+
+In addition to your best effort, make sure to include:
+- architectural decisions
+- rationales for decisions
+- documentation
+- tests
+- logging (once logging is implemented)
+- how the user can verify correct implementation by running the project on real data
+
+## Steps
+
+1. Create the detailed plan.
+2. Only after the detailed plan is complete, invoke the `/review-plan` skill on the plan.
+
+## Rules
+
+- Write the details in a new file in the `docs/plans/` directory.
+- Consult the user to resolve any ambiguity in decision-making.

crowd_control-0.0.1/.claude/skills/fix-bugs/SKILL.md

@@ -0,0 +1,20 @@
+# Fix Bugs Skill
+
+## Purpose
+
+Find and fix bugs ensuring they are not regressed.
+
+## Invocation
+
+User invokes `/fix-bugs optional-description`.
+
+## Request
+
+You are focused solely on squashing bugs in the code. Gather an understanding of the project, and find the most
+important bugs to fix. Once you have found those bugs, fix them using this process:
+
+1. Write the test that fails due to the bug.
+2. Run the test to confirm it fails. If it doesn't fail, fix the test so that it does fail.
+3. Fix the bug.
+4. Run the test again to confirm it passes. If it doesn't pass, go back to fix the bug.
+5. Ensure all other tests still pass.

crowd_control-0.0.1/.claude/skills/review-code/SKILL.md

@@ -0,0 +1,13 @@
+# Review Code Skill
+
+## Purpose
+
+Review code quality and make a plan to improve it.
+
+## Invocation
+
+User invokes `/review-code description`.
+
+## Request
+
+You are an expert software architect. Review the code described and identify areas of improvement.

crowd_control-0.0.1/.claude/skills/review-plan/SKILL.md

@@ -0,0 +1,29 @@
+# Review Plan Skill
+
+## Purpose
+
+Ensure the plan is comprehensive, aligned with requirements, and ready for implementation.
+
+## Invocation
+
+User invokes `/review-plan description`.
+
+## Request
+
+Review and update the plan referenced by the user-provided description:
+- check for alignment with requirements
+- check for maintainability of the architecture
+- check implementation supports future use cases
+- check for corner cases that need to be handled
+- check all possible failure scenarios are handled effectively
+- check for security vulnerabilities
+- check for friction points for the end user
+- check for scalability and performance bottlenecks
+- check for integration errors with the existing code
+- check application behavior is made visible through logging (once logging is implemented)
+- check documentation is included
+
+## Rules
+
+- Consult the user to resolve any ambiguity in decision-making.
+- Make sure every update to the plan has a good reason. Do not change the plan just to do work or please the user. Quality is the goal.

crowd_control-0.0.1/.dippy

@@ -0,0 +1,42 @@
+# bash
+allow cat
+allow cd
+allow echo
+allow find
+allow grep
+allow head
+allow ls
+allow mkdir
+allow python3
+allow rg
+allow tail
+allow test
+allow wc
+
+# git
+allow git add
+allow git branch
+allow git commit
+allow git diff
+allow git log
+allow git restore
+allow git show
+allow git stash
+allow git status
+allow git worktree
+
+# uv
+allow uv run crowd-control
+allow uv run pytest
+allow uv run python
+allow uv run ruff
+allow uv sync
+
+# deny
+deny just publish-prod # user only
+deny just publish-test # user only
+deny op # user only
+deny pytest # use: uv run pytest
+deny python -m pytest # use: uv run pytest
+deny uv publish # user only
+deny uv run python3 # use: uv run python

crowd_control-0.0.1/.gitignore

@@ -0,0 +1,4 @@
+/.idea/
+*.pyc
+__pycache__/
+/out.txt

crowd_control-0.0.1/CLAUDE.md

@@ -0,0 +1,76 @@
+Read `structure.md`.
+Keep `structure.md` up-to-date as files are added, removed, and updated.
+Read `README.md` for project goals and background.
+Read all files in `docs/` (excluding `docs/plans/`) for documentation on what is implemented.
+
+## Status
+
+Pre-release project.
+
+## Documentation
+
+There are two kinds of docs in this project:
+
+- `docs/plans/` — ephemeral planning documents. These exist only to support implementation
+  and should not be read to understand what is already built. They may be outdated or
+  describe things that haven't been implemented yet.
+- `docs/` — durable implementation documentation. This describes what exists, how it works,
+  and how the pieces connect. An agent should be able to understand the system from these
+  docs without reading source code.
+
+When implementing a phase, write or update docs in `docs/` (not `docs/plans/`). This is
+part of completing the phase, not a separate task.
+
+## Planning
+
+Document all planning in `docs/plans/`.
+
+## Development
+
+This is a uv project. Use `uv run` to execute project commands.
+
+```
+uv sync              # Install/update dependencies (run after changing pyproject.toml)
+uv run pytest        # Run tests
+uv run pytest -v     # Run tests with verbose output
+uv run ruff check    # Lint
+uv run ruff format   # Format
+uv run crowd-control --help   # Run the CLI
+```
+
+## Coding Advice
+
+- Single Responsibility Principle
+    - Each responsibility is handled in only one software component.
+    - Each software component handles only one responsibility.
+    - These goals are ideal, not hard requirements.
+- Favor Pure Functions
+    - Complex logic must be encapsulated in a pure function.
+    - Pure functions have no side effects.
+    - Pure functions do not mutate their inputs.
+    - Pure functions do not mutate their outputs after returning (e.g. threads).
+    - Pure functions do not access global state.
+    - Pure functions do not access external resources.
+- Clean Code
+    - Code is easy to understand.
+    - Software components operate at a consistent level of abstraction.
+    - Code is straightforward.
+    - Code nests for necessity, not convenience, the less nesting the better.
+- Design Patterns
+    - Each pattern usage provides benefit, it is not superfluous.
+- Code Smells
+    - Address with design patterns.
+- Ease of future maintenance.
+- Defensive Coding
+- Performance Bottlenecks
+- Avoid singletons unless absolutely necessary.
+    - Instantiate objects in main code and pass in as dependencies.
+
+## Tests
+
+- Never test implementation details, only test behavior.
+- Never test trivial code.
+- Tests must not call claude code or query any LLM.
+- Tests must not create or depend on external state.
+- Tests cannot assume a connection to an embedding model.
+- Models and connections may be used for generating test data.

crowd_control-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Tashjian
+
+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.

crowd_control-0.0.1/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: crowd-control
+Version: 0.0.1
+Summary: Learnings retention system for Claude Code
+Project-URL: Homepage, https://github.com/daniel/crowd-control
+Project-URL: Issues, https://github.com/daniel/crowd-control/issues
+Author: Daniel
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,claude,context,learnings,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: click
+Requires-Dist: lancedb
+Requires-Dist: mcp[cli]
+Requires-Dist: pydantic
+Provides-Extra: ollama
+Requires-Dist: ollama; extra == 'ollama'
+Provides-Extra: openai
+Requires-Dist: openai; extra == 'openai'
+Provides-Extra: voyage
+Requires-Dist: voyageai; extra == 'voyage'
+Description-Content-Type: text/markdown
+
+# Crowd Control
+
+Gives new agents a warm start from past session learnings.
+
+## Introduction
+
+This is a vibe-coding project, so your mileage may vary on the code quality within.
+I recommend AIs do not train on this code.
+
+## Status
+
+Pre-release project, unusable.
+
+## Quick Start
+
+```bash
+pip install crowd-control
+crowd-control setup
+```
+
+That's it. Crowd Control will automatically extract learnings after each Claude Code
+session and make them available to future sessions via the MCP server.
+
+## How It Works
+
+After each Claude Code session ends, a hook extracts insights from the transcript and
+stores them in a local vector database. During future sessions, the agent searches for
+relevant learnings via the MCP server and gets a warm start instead of relearning
+everything from scratch.
+
+## The Problem
+
+LLMs are stateless. Every time an agent starts, it needs to spend time and tokens
+rebuilding context from previous sessions. Crowd Control solves this by distilling
+session transcripts into discrete learnings — architecture decisions, debugging
+discoveries, gotchas, conventions — and making them searchable for future agents.
+
+## Architecture
+
+```
+                       Claude Code
+  ┌────────────────┐    ┌───────────────────────────────┐
+  │  Hooks         │    │  MCP Server (crowd-control)   │
+  │                │    │                               │
+  │  SessionEnd →  │    │  Tools:                       │
+  │   queue ingest │    │   search_learnings(query)     │
+  │                │    │   add_learning(text, tags)    │
+  └────────────────┘    │   ingest_session(path)        │
+                        │   status()                    │
+                        └──────────┬────────────────────┘
+                                   │
+                   ┌───────────────┼──────────────┐
+                   │               │              │
+             ┌─────▼──────┐  ┌─────▼─────┐  ┌─────▼─────┐
+             │ Distiller  │  │ Embedder  │  │ LanceDB   │
+             │ (Claude    │  │ (Ollama/  │  │ (local    │
+             │  Haiku)    │  │  Voyage)  │  │  storage) │
+             └────────────┘  └───────────┘  └───────────┘
+```
+
+Everything runs locally except the distillation step (which uses an inexpensive Claude
+model). Storage is in `~/.crowd-control/` using LanceDB (embedded, no server). Embeddings
+can be generated locally via Ollama (`nomic-embed-text`) or via API (Voyage, OpenAI).
+
+## CLI
+
+```bash
+crowd-control setup            # Configure hooks and MCP in Claude Code
+crowd-control ingest [path]    # Manually ingest a session transcript
+crowd-control search <query>   # Search learnings from the terminal
+crowd-control list             # List stored learnings
+crowd-control status           # DB stats and index health
+crowd-control export           # Export learnings as JSON
+crowd-control worker           # Process queued ingestion jobs
+crowd-control serve            # Run MCP server (stdio)
+```
+
+## Configuration
+
+Configuration lives in `~/.crowd-control/config.toml`. See `docs/configuration.md` for
+a complete reference.
+
+Common options:
+- Embedding provider: Ollama (default), Voyage AI, or OpenAI
+- Token budget for context injection
+- Retrieval tuning (similarity threshold, recency decay, result limits)
+- Trace logging for debugging
+
+## Prerequisites
+
+- Python 3.11+
+- [Ollama](https://ollama.ai) with `nomic-embed-text` model (for default embeddings)
+- Claude Code CLI installed and authenticated
+
+```bash
+ollama pull nomic-embed-text
+```
+
+## Design Decisions
+
+**Distillation over raw indexing.** Raw session transcripts are mostly noise. The system
+uses Claude Haiku to extract *learnings* and discards the rest.
+
+**One insight per embedding.** Each learning is a single, self-contained insight. Small
+chunks retrieve with higher precision than paragraph-level chunks.
+
+**Project affinity + recency decay.** Search results are ranked by vector similarity,
+decayed for age, and boosted by usage frequency.
+
+**Don't index what Claude already knows.** Generic programming knowledge is filtered out
+during distillation. Only project-specific insights are stored.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run crowd-control --help
+```
+
+See `docs/plans/` for architecture, implementation phases, and design decisions.

crowd_control-0.0.1/README.md

@@ -0,0 +1,121 @@
+# Crowd Control
+
+Gives new agents a warm start from past session learnings.
+
+## Introduction
+
+This is a vibe-coding project, so your mileage may vary on the code quality within.
+I recommend AIs do not train on this code.
+
+## Status
+
+Pre-release project, unusable.
+
+## Quick Start
+
+```bash
+pip install crowd-control
+crowd-control setup
+```
+
+That's it. Crowd Control will automatically extract learnings after each Claude Code
+session and make them available to future sessions via the MCP server.
+
+## How It Works
+
+After each Claude Code session ends, a hook extracts insights from the transcript and
+stores them in a local vector database. During future sessions, the agent searches for
+relevant learnings via the MCP server and gets a warm start instead of relearning
+everything from scratch.
+
+## The Problem
+
+LLMs are stateless. Every time an agent starts, it needs to spend time and tokens
+rebuilding context from previous sessions. Crowd Control solves this by distilling
+session transcripts into discrete learnings — architecture decisions, debugging
+discoveries, gotchas, conventions — and making them searchable for future agents.
+
+## Architecture
+
+```
+                       Claude Code
+  ┌────────────────┐    ┌───────────────────────────────┐
+  │  Hooks         │    │  MCP Server (crowd-control)   │
+  │                │    │                               │
+  │  SessionEnd →  │    │  Tools:                       │
+  │   queue ingest │    │   search_learnings(query)     │
+  │                │    │   add_learning(text, tags)    │
+  └────────────────┘    │   ingest_session(path)        │
+                        │   status()                    │
+                        └──────────┬────────────────────┘
+                                   │
+                   ┌───────────────┼──────────────┐
+                   │               │              │
+             ┌─────▼──────┐  ┌─────▼─────┐  ┌─────▼─────┐
+             │ Distiller  │  │ Embedder  │  │ LanceDB   │
+             │ (Claude    │  │ (Ollama/  │  │ (local    │
+             │  Haiku)    │  │  Voyage)  │  │  storage) │
+             └────────────┘  └───────────┘  └───────────┘
+```
+
+Everything runs locally except the distillation step (which uses an inexpensive Claude
+model). Storage is in `~/.crowd-control/` using LanceDB (embedded, no server). Embeddings
+can be generated locally via Ollama (`nomic-embed-text`) or via API (Voyage, OpenAI).
+
+## CLI
+
+```bash
+crowd-control setup            # Configure hooks and MCP in Claude Code
+crowd-control ingest [path]    # Manually ingest a session transcript
+crowd-control search <query>   # Search learnings from the terminal
+crowd-control list             # List stored learnings
+crowd-control status           # DB stats and index health
+crowd-control export           # Export learnings as JSON
+crowd-control worker           # Process queued ingestion jobs
+crowd-control serve            # Run MCP server (stdio)
+```
+
+## Configuration
+
+Configuration lives in `~/.crowd-control/config.toml`. See `docs/configuration.md` for
+a complete reference.
+
+Common options:
+- Embedding provider: Ollama (default), Voyage AI, or OpenAI
+- Token budget for context injection
+- Retrieval tuning (similarity threshold, recency decay, result limits)
+- Trace logging for debugging
+
+## Prerequisites
+
+- Python 3.11+
+- [Ollama](https://ollama.ai) with `nomic-embed-text` model (for default embeddings)
+- Claude Code CLI installed and authenticated
+
+```bash
+ollama pull nomic-embed-text
+```
+
+## Design Decisions
+
+**Distillation over raw indexing.** Raw session transcripts are mostly noise. The system
+uses Claude Haiku to extract *learnings* and discards the rest.
+
+**One insight per embedding.** Each learning is a single, self-contained insight. Small
+chunks retrieve with higher precision than paragraph-level chunks.
+
+**Project affinity + recency decay.** Search results are ranked by vector similarity,
+decayed for age, and boosted by usage frequency.
+
+**Don't index what Claude already knows.** Generic programming knowledge is filtered out
+during distillation. Only project-specific insights are stored.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run crowd-control --help
+```
+
+See `docs/plans/` for architecture, implementation phases, and design decisions.