CamMonitor/README.md

CamMonitor

Overview

CamMonitor is a self-hosted security camera footage viewer. It provides the Go HTTP server, a /health endpoint, environment-based configuration, SQLite startup and migrations, bcrypt login, session cookies, admin user management, an in-memory footage index, and Docker Compose deployment.

Getting Started

Copy the sample environment file and adjust it for your footage directory:

cp .env.example .env

Start the app with Docker Compose:

docker compose up --build

Verify the server is running:

curl http://localhost:8080/health

The response should be:

{"status":"ok"}

Open http://localhost:8080/login and sign in with ADMIN_USER and ADMIN_PASS. On the first run, CamMonitor creates that bootstrap admin account only when the user table is empty. After login, admins can add or delete users at /admin/users.

Configuration

Variable	Default	Description
PORT	8080	Host port published by Docker Compose
LISTEN_ADDR	:8080	TCP address used by the Go server
FOOTAGE_ROOT	/footage	Camera footage directory inside the container
DB_PATH	/data/cammonitor.db	SQLite database path
ADMIN_USER	admin	Bootstrap admin username created on first run when no users exist
ADMIN_PASS	changeme	Bootstrap admin password created on first run when no users exist
SESSION_TTL	24h	Session cookie lifetime
SCAN_INTERVAL	5m	Footage rescan interval

Authentication

All app routes except /health, /login, and POST /login require a valid session cookie. Unauthenticated requests are redirected to /login. Admin-only pages return 403 Forbidden for signed-in non-admin users.

The login form posts credentials to /login. Successful login sets an HTTP-only session cookie and redirects to /; invalid credentials return 401 Unauthorized. POST /logout deletes the server-side session, clears the cookie, and redirects back to /login.

Admin users can manage accounts at /admin/users. New users are created with bcrypt-hashed passwords, and deleting a user also removes their sessions through the SQLite foreign key cascade.

Browsing Footage

After login, / redirects to the newest indexed day's image browser at /day/YYYYMMDD/images. The day overview at /day/YYYYMMDD shows the available image and video counts with links to /day/YYYYMMDD/images and /day/YYYYMMDD/videos.

The image browser at /day/YYYYMMDD/images shows a horizontal thumbnail strip and a full-size viewer for the selected image. Use the on-screen previous and next buttons or the left and right arrow keys to move through images for the day; navigation wraps at the ends. The current image is deep-linkable with ?idx=N, where N is the zero-based image index.

Original JPEGs are served from /raw/image/<relative-path> after validating that the path stays inside FOOTAGE_ROOT. Thumbnails are served from /thumb/image/<relative-path> as cached 160x90 JPEGs generated in memory only.

The video browser at /day/YYYYMMDD/videos uses the same strip-and-viewer layout with an HTML5 player, wraparound arrow navigation, and ?idx=N deep links. Video thumbnails are served from /thumb/video/<relative-path>, and /stream/video/<relative-path> remuxes the source clip to fragmented MP4 on demand with ffmpeg without re-encoding.

On desktop widths, the app shows a dark sidebar with indexed days grouped by month. On smaller screens, the sidebar is replaced by a drawer trigger in the header and a fixed bottom tab bar for switching between Images and Videos.

Footage Layout

Footage is mounted read-only at /footage in the container. CamMonitor scans this tree on startup and then rescans it on the SCAN_INTERVAL schedule. Days are indexed from YYYYMMDD directories, with images and videos sorted chronologically inside each day.

The expected directory format is:

YYYYMMDD/
  images/
    AYYMMDDHHMMSSNN.jpg
  record/
    AYYMMDD_HHMMSS_HHMMSS.265

AI Workflow

This project includes the persistent planner/implementer/reviewer workflow with file-based coordination, plus the PO orchestration layer. Manual and auto are two runtime modes for the same scaffold: they use the same generated files, task board, and review gate. Fewer role sessions means less coordination overhead and lower token cost.

Modes

This scaffold supports two workflow profiles that share the same generated files, task board, plan, review log, and handoff log.

• full keeps the planner, implementer, reviewer, and optional PO split.
• lite keeps the planner but replaces separate implementer/reviewer sessions with one aide dev session.

Profile	Sessions and launchers	Who drives work	Commit cadence	PO support	Recommended fit
full	aide plan, aide implement, aide review, optional aide po	Separate role sessions with explicit implement/review handoffs	One final task commit after reviewer approval	yes	Larger, riskier, or more review-heavy changes
lite	aide plan, aide dev	Planner plus one dev session that implements and reviews, then halts for human approval at ready_for_review	One real commit per task, including all_task	no	Smaller changes or lower-coordination work

How to switch

aide profile full
aide profile lite

Use aide profile full to return to the split workflow, or aide profile lite to switch to the dev-session flow.

full is the default for new scaffolds. When you switch to lite, aide implement, aide review, and aide po refuse and point you at aide dev. When you switch back to full, aide dev refuses and points you at aide implement and aide review.

Runtime modes

• Manual mode: start the planner, implementer, and reviewer in separate terminals, then drive each session yourself with the documented text commands.
• Auto mode: run aide po to start the PO session, which uses MCP tools to coordinate the post-planning implementer/reviewer workflow for you.

Concepts

Cycle — a unit of work on a feature branch. One cycle = one branch = one PR.

Roles and file ownership:

Role	Reads	Writes
PO	.ai/TASKS.md, .ai/PLAN.md, .ai/REVIEW.md, .ai/prompts/po.md	MCP session commands via aide po
Planner	ROADMAP.md	.ai/PLAN.md, .ai/TASKS.md
Implementer	.ai/PLAN.md, .ai/REVIEW.md	source code, .ai/TASKS.md
Reviewer	.ai/PLAN.md, commits	.ai/REVIEW.md, .ai/TASKS.md

Status flow:

in_planning → ready_for_implement → in_implementation → ready_for_review → in_review → ready_to_commit → done
                                          ↑                                     |
                                          └──── changes_requested ◄─────────────┘

Start a new development cycle

# Edit ROADMAP.md with your goals first, then:
aide cycle start feature/<scope>

Full profile quick start

aide plan          # terminal 1
aide implement     # terminal 2
aide review        # terminal 3

Launch each role once, then keep those sessions open for the rest of the cycle.

Role launchers read default agent/model settings from .ai/config.json. To override, pass the agent first, then any CLI flags. Example: aide review claude --model sonnet Claude starts interactively by default, and the Codex launcher uses interactive codex mode so the session stays open for role commands.

Lite profile quick start

aide profile lite
aide plan          # terminal 1
aide dev           # terminal 2

The dev session handles implementation and review, then halts for human approval at ready_for_review. In lite mode, aide implement, aide review, and aide po refuse and point you at aide dev.

Start the PO orchestrator (auto mode)

aide po

The PO session drives the post-planning task board flow through the aide MCP server. PO orchestration is available only in the full profile. By default, aide po launches Claude with --model haiku, and aide po codex launches Codex with -m gpt-5.4-mini. .ai/config.json can override those defaults, and an explicit CLI --model or -m flag takes precedence. If no tasks are in ready_for_implement or later, run the planner first. The normal MCP completion path is session_run followed by session_wait, then a re-read of .ai/TASKS.md; session_get_output is for debugging only. The MCP server appends structured debug logs to .ai/mcp-server.log, and the scaffold gitignore excludes that file.

Drive work inside the existing sessions

planner> start_plan
implementer> next_task T-001
reviewer> next_task T-001
implementer> commit_task T-001
dev> next_task T-001
dev> commit_task T-001
implementer> rework_task T-001
aide cycle end 0.7.0

Cross-platform CLI equivalents: aide cycle end [VERSION] closes the cycle outside the persistent role session, and aide pr [--dry-run] creates or updates the branch PR.

Planner commands:

Before start_plan, freeform conversation with the planner is the roadmap-refinement phase. Use it to sharpen scope, acceptance criteria, constraints, and trade-offs directly in ROADMAP.md. start_plan is the explicit handoff into formal planning.

Command	Description
start_plan	Read ROADMAP.md, write .ai/PLAN.md and .ai/TASKS.md
rework_plan [TASK_ID]	Revisit the plan when scope or approach changes

Implementer commands:

Command	Description
next_task [TASK_ID]	Pick up the next ready_for_implement task
commit_task [TASK_ID]	Turn a ready_to_commit task into one clean final commit, including task-specific .ai/ artifacts
rework_task [TASK_ID]	Address changes_requested findings from .ai/REVIEW.md
aide cycle end [VERSION]	Close the cycle after all tasks reach done, committing remaining .ai/ artifacts with a Release-As: footer
status_cycle [TASK_ID]	Show task status and recommended next action

Reviewer commands:

Command	Description
next_task [TASK_ID]	Pick up the next ready_for_review task and run review plus verification
status_cycle [TASK_ID]	Show task status and recommended next action

File map

File	Purpose	Tracked
.ai/PLAN.md	Current plan	yes
.ai/TASKS.md	Task board with status	yes
.ai/prompts/po.md	PO orchestration prompt for auto mode	yes
.ai/REVIEW.md	Review findings	yes (tracked cycle log)
.ai/HANDOFF.md	Runtime handoff log	yes (tracked cycle log)
.ai/config.json	Per-role launch defaults	yes
ROADMAP.md	Cycle goals (edit before planning)	yes
AGENTS.md	Project-specific and workflow-managed agent rules	yes
CLAUDE.md	Agent instruction entry point (@AGENTS.md)	yes
aide po	Launch the PO orchestration session	yes

Create a PR

aide pr

Full workflow details and session recovery rules are in AGENTS.md.