war-room-starter

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

war-room-starter

★ 22 Open GitHub ↗

Self-hosted ops dashboard fed by markdown briefs in your project folders

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# War Room Starter

A self-hosted operations dashboard that pulls from markdown briefs in your project folders. One static HTML file, one Python scanner, no server, no database, no SaaS.

## What this is

You keep a markdown file inside each project folder — your "canonical brief." A small Python scanner walks those folders, reads the briefs, and bakes the data into `war-room.html`. You open the HTML in any browser and see one tab per project: file activity, last-touched timestamps, and the brief itself rendered live.

That's the whole loop. Update a brief, scanner picks it up on the next pass, dashboard reflects it.

## Why

If you run multiple side projects and care about not losing context between sessions, the brief becomes the source of truth. The dashboard is just a view over the briefs — no separate state to drift.

## Requirements

- Python 3.9 or newer
- Any modern browser

That's it.

## Quick start

```bash
git clone https://github.com/YOUR_USERNAME/war-room-starter.git
cd war-room-starter
cp config.example.json config.json
```

Then on Windows, double-click `start-watcher.bat`. On macOS or Linux:

```bash
./start-watcher.sh
```

Open `war-room.html` in your browser. You'll see three example projects (Project A, B, C) populated from the briefs in `example-projects/`. The watcher rescans every 30 seconds; hit the **REFRESH** button in the dashboard to re-read the file.

## Add your own project

1. **Drop a brief into your project folder.** Anywhere on disk. Name the file whatever you want — `PROJECT_BRIEF.md` is the default. Use the example briefs in `example-projects/` as a template.

2. **Edit `config.json`.**
   - Change `projects_root` to the folder that contains your project folders, e.g. `"~/code"` or `"C:\\Projects"`. Use `\\` (double backslash) for Windows paths in JSON, or just forward slashes — Python handles both.
   - Add an entry under `projects`:
     ```json
     {
       "name": "my-thing",
       "label": "MY THING",
       "brief_filename": "PROJECT_BRIEF.md",
       "tagline": "One-line description shown above the brief"
     }
     ```
   - `name` must match the folder name on disk under `projects_root`.

3. **Refresh.** If the watcher is running, it picks up changes on the next scan. Otherwise re-run `refresh-once`. A new tab appears for your project with a live card and the rendered brief.

You can register as many projects as you want — the dashboard just keeps adding tabs.

## Workflow diagrams in your briefs

Add a fenced code block tagged `mermaid` and it renders as a diagram in the project tab.

````markdown
```mermaid
flowchart LR
    A[Source] --> B[Process] --> C[Output]
```
````

See the example briefs for working syntax. [Mermaid syntax docs](https://mermaid.js.org/intro/).

## Auto-start on login

So the watcher is running every time you start your machine.

### Windows

1. Press `Win + R`, type `shell:startup`, press Enter. A folder opens.
2. Right-click in that folder → New → Shortcut.
3. Browse to `start-watcher.bat`, finish the wizard.
4. Right-click the shortcut you just made → Properties → set **Run** to `Minimized`.

It boots a background console every login.

### macOS

```bash
# In war-room-starter/
mkdir -p ~/Library/LaunchAgents
cat > ~/Library/LaunchAgents/com.warroom.watcher.plist <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>com.warroom.watcher</string>
  <key>ProgramArguments</key>
  <array>
    <string>$(pwd)/start-watcher.sh</string>
  </array>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>WorkingDirectory</key><string>$(pwd)</string>
</dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/com.warroom.watcher.plist
```

To stop: `launchctl unload ~/Library/LaunchAgents/com.warroom.watcher.plist`.

### Linux (systemd user service)

```bash
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/war-room.service <<EOF
[Unit]
Description=War Room watcher

[Service]
ExecStart=$(pwd)/start-watcher.sh
WorkingDirectory=$(pwd)
Restart=always

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now war-room.service
```

## How it works under the hood

```
┌────────────────────────┐                                                    
│ Your project folders   │                                                    
│  /code/my-thing/       │                                                    
│    PROJECT_BRIEF.md  ──┼──┐                                                 
│  /code/other/          │  │                                                 
│    PROJECT_BRIEF.md  ──┼──┤                                                 
└────────────────────────┘  │                                                 
                            ▼                                                 
                  ┌─────────────────┐       ┌──────────────────────────────┐
                  │   scanner.py    │  ───▶ │  war-room.html               │
                  │  (every 30s)    │       │  • baked-in JSON payload     │
                  └─────────────────┘       │  • marked.js renders briefs  │
                                            │  • mermaid renders diagrams  │
                                            └──────────────────────────────┘
                                                          │
                                                          ▼
                                                 your browser
```

The scanner only modifies the block between two HTML comments:

```html

<script>window.WAR_ROOM_DATA = {...};</script>

```

Everything else in `war-room.html` is left alone, so your local edits to layout, CSS, or static content survive scans.

## Configuration reference

| Field | Default | Notes |
| --- | --- | --- |
| `dashboard_title` | `"MY WAR ROOM"` | Shown in the topbar and as the page title. |
| `projects_root` | `"./example-projects"` | Absolute path or relative to `scanner.py`. Where your project folders live. |
| `watch_interval_secs` | `30` | How often the watcher rescans. |
| `max_brief_bytes` | `1000000` | Briefs larger than this are skipped (with an error in the dashboard). |
| `ignore_dirs` | see config | Folders the file-counter skips inside each project (`node_modules`, `.git`, etc.). |
| `projects[]` | `[]` | One entry per project tab. |
| `projects[].name` | required | Folder name under `projects_root`. |
| `projects[].label` | `name` | Display name on the tab. |
| `projects[].brief_filename` | required | Markdown file inside the project folder. |
| `projects[].tagline` | `""` | Optional one-liner shown above the brief. |

## Customizing the look

`war-room.html` is one self-contained file. Edit the `<style>` block to change colors, fonts, spacing. The terminal aesthetic (orange + green + black, Courier New) is in there. CSS variables would be a clean refactor if you want to theme it.

## Security

This is a single static HTML file you open from `file://`. Nothing is sent anywhere. Two CDN dependencies are loaded for rendering: [marked](https://github.com/markedjs/marked) for markdown and [mermaid](https://github.com/mermaid-js/mermaid) for diagrams, both from cdnjs. If you're offline they degrade gracefully — markdown renders as raw text, mermaid blocks render as code.

**Don't put secrets in your briefs.** API keys, passwords, customer data. The briefs render verbatim into the HTML.

## Troubleshooting

**The dashboard says "no scan data."** The watcher hasn't run yet, or it ran but couldn't find the markers. Check that you ran `start-watcher` (or `refresh-once`) and that there are no Python errors in its terminal.

**A project tab shows "Brief not found."** Double-check the `name` in `config.json` matches the folder name exactly, and `brief_filename` matches the markdown file name. Capitalization matters.

**The dashboard looks stale.** Hit the REFRESH button in the topbar — it just reloads the HTML from disk. Browsers don't auto-refresh `file://` pages.

**Mermaid diagrams aren't rendering.** Make sure your fenced code block is tagged `mermaid` (lowercase) and the syntax is valid. Open the browser console for errors.

**The dashboard format breaks after a scan.** Open `scanner.py`'s output — it should print `[scanner] HH:MM:SS scanned N projects, M briefs -> war-room.html` on success. If it errors out, the markers may be missing or the JSON injection failed.

## License

MIT. See `LICENSE`.

## Credit

Built solo, in public. If you fork it, let me know what you build with it.

war-room-starter

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README