Skip to content

Commit 5da8730

Browse files
SuperInstanceSuperInstance
committed
[docs] README — all-night thinking agent
1 parent 2c1250e commit 5da8730

1 file changed

Lines changed: 142 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
# Murmur‑Agent 🫧
2+
**All‑night thinking git‑agent** – drop it into any project, give it a topic, and let it think while you sleep.
3+
4+
[![npm version](https://img.shields.io/npm/v/murmur-agent.svg)](https://www.npmjs.com/package/murmur-agent)
5+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6+
[![GitHub stars](https://img.shields.io/github/stars/yourorg/murmur-agent.svg?style=social&label=Star)](https://github.com/yourorg/murmur-agent)
7+
[![Build Status](https://img.shields.io/github/actions/workflow/status/yourorg/murmur-agent/ci.yml?branch=main)](https://github.com/yourorg/murmur-agent/actions)
8+
9+
---
10+
11+
## Table of Contents
12+
- [What is Murmur‑Agent?](#what-is-murmur-agent)
13+
- [Features](#features)
14+
- [Installation](#installation)
15+
- [Commands](#commands)
16+
- [How it Works](#how-it-works)
17+
- [How it Thinks](#how-it-thinks)
18+
- [Use Cases](#use-cases)
19+
- [C CLI Version](#c-cli-version)
20+
- [Comparison: TypeScript vs C](#comparison-typescript-vs-c)
21+
- [Contributing](#contributing)
22+
- [License](#license)
23+
24+
---
25+
26+
## What is Murmur‑Agent?
27+
Murmur‑Agent is a **budget‑agnostic, local‑first, git‑native** assistant that spends the night (or any amount of time) generating ideas, research notes, and technical insights around a topic you give it. Every thought becomes a Git commit, every insight a file—so your knowledge is always version‑controlled.
28+
29+
---
30+
31+
## Features
32+
- **Drop‑in**: Works with any existing repo; no special scaffolding required.
33+
- **Budget‑agnostic**: Operates with as few as 10 API calls/day or as many as 10 000.
34+
- **Local‑first**: Can run completely offline on local hardware—no API key needed.
35+
- **Git‑native**: Each thought is a commit; each insight is a file in `murmur-output/`.
36+
- **Dual implementation**: TypeScript (Node.js) **and** a tiny C CLI (`murmur-cli.c`).
37+
- **Emoji branding**: 🫧 bubbles rising to the surface of your codebase.
38+
39+
---
40+
41+
## Installation
42+
43+
### TypeScript (Node.js)
44+
```bash
45+
npm install murmur-agent
46+
npx murmur think --topic "distributed systems patterns"
47+
```
48+
49+
### C CLI (edge devices)
50+
```bash
51+
# Compile the C binary (POSIX systems, Raspberry Pi, Jetson, etc.)
52+
gcc -o murmur c/murmur-cli.c -lm
53+
54+
# Run the same command without Node.js
55+
./murmur think "distributed systems patterns"
56+
```
57+
58+
The C binary stores its state under `~/.murmur/`.
59+
60+
---
61+
62+
## Commands
63+
| Command | Description |
64+
|---------|-------------|
65+
| `npx murmur think --topic "your topic"` | Start a thinking session (TS) |
66+
| `./murmur think "your topic"` | Start a thinking session (C) |
67+
| `murmur scan <directory>` | Ingest files into the knowledge tensor |
68+
| `murmur budget` | Show remaining daily API budget |
69+
| `murmur export` | Export all thoughts as a single markdown file |
70+
| `murmur status` | Display current session state (topic, budget, progress) |
71+
72+
All commands create or update files under `murmur-output/` and automatically commit them.
73+
74+
---
75+
76+
## How it Works
77+
1. **Provide a topic & budget** – e.g., `npx murmur think --topic "micro‑service observability"`.
78+
2. Murmur‑Agent runs four **thinking strategies** (see below) to generate a **knowledge tensor** that grows with each iteration.
79+
3. Each generated thought is written to a markdown file in `murmur-output/` and committed to the repo.
80+
4. When the session ends (or the budget is exhausted), you can `murmur export` to collect everything into a single document.
81+
82+
### How it Thinks
83+
Murmur‑Agent cycles through four complementary strategies:
84+
85+
| Strategy | Goal | What it does |
86+
|----------|------|--------------|
87+
| **Diverge** | Explore breadth | Generates a wide‑range list of ideas, related concepts, and possible directions. |
88+
| **Converge** | Focus depth | Picks the most promising threads from the divergence phase and expands them with detail. |
89+
| **Challenge** | Test robustness | Actively questions assumptions, surfaces edge‑cases, and highlights potential pitfalls. |
90+
| **Synthesize** | Create new insight | Combines the refined ideas into cohesive narratives, diagrams, or actionable recommendations. |
91+
92+
The cycle repeats until the budget is spent or the user stops the session.
93+
94+
---
95+
96+
## Use Cases
97+
- **Research exploration overnight** – Let Murmur‑Agent skim papers, generate hypotheses, and outline a literature review.
98+
- **Brainstorming product ideas** – Produce feature lists, market angles, and MVP scopes while you sleep.
99+
- **Exploring technical trade‑offs** – Compare architectures, list pros/cons, and surface hidden costs.
100+
- **Building knowledge tensors from codebases** – Scan a repo, extract patterns, and create a living design document.
101+
- **Background thinking** – Run a low‑budget session on a Raspberry Pi and get incremental insights every day.
102+
103+
---
104+
105+
## C CLI Version
106+
- **Compilation**: `gcc -o murmur c/murmur-cli.c -lm`
107+
- **No Node.js**: Ideal for constrained environments.
108+
- **Runs on**: Raspberry Pi, Jetson, any POSIX‑compatible system.
109+
- **State location**: `~/.murmur/` (separate from the repo to keep the binary lightweight).
110+
- **Same command surface** as the TypeScript version.
111+
112+
---
113+
114+
## Comparison: TypeScript vs C
115+
116+
| Aspect | TypeScript (Node) | C CLI |
117+
|--------|-------------------|-------|
118+
| **Runtime** | Node.js (≥14) | Native binary |
119+
| **Installation** | `npm install murmur-agent` | `gcc -o murmur murmur-cli.c -lm` |
120+
| **Dependencies** | npm packages, optional OpenAI SDK | Only standard C library + `-lm` |
121+
| **Platform** | Cross‑platform (Windows, macOS, Linux) | POSIX only (Linux, macOS, Raspberry Pi, Jetson) |
122+
| **State storage** | `murmur-output/` in repo | `~/.murmur/` |
123+
| **Extensibility** | Easy to add plugins via npm | Requires recompilation |
124+
| **Performance** | Slightly slower start‑up, richer ecosystem | Faster start‑up, lower memory footprint |
125+
| **Use case** | Development machines, CI pipelines | Edge devices, offline environments |
126+
127+
---
128+
129+
## Contributing
130+
Contributions are welcome! Please:
131+
132+
1. Fork the repo and create a feature branch.
133+
2. Follow the existing code style (Prettier for TS, clang‑format for C).
134+
3. Write tests for new functionality (`npm test` for TS, `make test` for C).
135+
4. Submit a Pull Request with a clear description of the change.
136+
137+
See `CONTRIBUTING.md` for detailed guidelines.
138+
139+
---
140+
141+
## License
142+
Murmur‑Agent is released under the **MIT License**. See the `LICENSE` file for details.

0 commit comments

Comments
 (0)