DOCSEARCHbyAlgolia
Submit Docs

Envisaged

repository·main·Indexed 41 days ago

https://github.com/utensils/envisaged

A Nix-first Git history and system log visualization tool powered by Gource and FFmpeg. Envisaged renders cinematic timelines of repository activity or machine system logs (journal, kernel, auth) using a variety of visual templates, including core, compare, split, and relation families. It features a CLI and a mobile-first Web UI, supporting multi-repo comparisons and normalized timeline syncing.

Tokens
4.2K
Snippets
12
Records
19
Agent score
50%

What's inside Envisaged

  1. Quick start with Nix

    main

    You can run Envisaged immediately using Nix without manual installation. The project provides several entry points for the CLI and Web UI.

    CLI Usage

    Use nix run . to run the default CLI app, or specify targets like .#cli or .#web.

    Common Render Tasks

    • Single Repo: nix run . -- -o output.mp4 -t "Repo History" .
    • Multi-Repo Comparison: nix run . -- --multi-dir ~/Projects/utensils --template compare-panel --sync-timing auto -o compare.mp4
    • System Logs: nix run . -- --system-log journal --system-log-since "24 hours ago" --template tokyo-night --legend all -o system-journal.mp4
    # CLI (default app)
nix run . -- --help

# Explicit app targets
nix run .#cli -- --help
nix run .#web

# Render current repo
nix run . -- -o output.mp4 -t "Repo History" .

# Render multi-repo compare
nix run . -- --multi-dir ~/Projects/utensils --template compare-panel --sync-timing auto -o compare.mp4

# Render system logs (journalctl -> timeline)
nix run . -- --system-log journal --system-log-since "24 hours ago" --template tokyo-night --legend all -o system-journal.mp4

  2. Install Envisaged as a Systemd user service

    main

    To run the Web UI as a background service, use the provided Systemd unit files located in systemd/user/.

    1. Copy the service files to your user config directory.
    2. Reload the systemd daemon.
    3. Enable and start the desired service (stable or dev).

    Note: Use envisaged-web-dev.service if you need hot-reloading during development.

    mkdir -p ~/.config/systemd/user
cp systemd/user/envisaged-web*.service ~/.config/systemd/user/
systemctl --user daemon-reload

# stable mode
systemctl --user enable --now envisaged-web.service

# OR dev/hot-reload mode
systemctl --user disable --now envisaged-web.service || true
systemctl --user enable --now envisaged-web-dev.service

# logs/status
systemctl --user status envisaged-web.service
journalctl --user -u envisaged-web.service -f

  3. Use the Envisaged Web UI

    main

    The Web UI provides a mobile-first interface for rendering Git histories and system logs. It defaults to single-repo mode but supports System Log modes (journal, kernel, auth).

    Running the Web UI

    Use the provided helper scripts for stable or development (hot-reload) environments:

    • Stable: ./scripts/web-prod (accessible at http://127.0.0.1:8787)
    • Hot Reload: ./scripts/web-dev

    Web UI Features

    • GitHub Search: Search for owner/repo to clone/update repos locally in /tmp/envisaged-web-repos.
    • Output Location: Rendered files are saved to ~/.openclaw/workspace/out/web/.
    • System Log Mode: Automatically applies a tokyo-night template with a services legend.
    # stable runtime
./scripts/web-prod
# open http://127.0.0.1:8787

# hot reload runtime
./scripts/web-dev

  5. How multi-repo and split templates work

    main

    Envisaged can visualize multiple repositories simultaneously using specific templates and the --multi-dir flag.

    • Comparison/Split Templates: Templates like split-quad, split-vertical, split-triple, split-focus, and split-matrix are designed to show multiple streams at once.
    • Syncing: When rendering multiple repositories, sync_timing is critical. Using smart mode ensures that the timelines of different repositories are normalized to a common time base and injects "sync pulses" (anchor/pulse events) to keep the visual cadence aligned.
    • Legend Behavior: In multi-repo modes, the legend mode defaults to repos to show which repository is currently active in each view.

  6. Render Git history videos via CLI

    main

    The envisaged CLI renders Git history visualizations using Gource and FFmpeg. It supports three primary input modes:

    1. Single Repository: Provide a local path or a Git URL.
    2. Multi-Repository: Provide a directory containing multiple Git repositories using --multi-dir to compare or split them.
    3. System Logs: Use --system-log to visualize system events (journal, kernel, or auth) as an event stream instead of file changes.

    Requirements:

    • gource, ffmpeg, xvfb-run, and bash must be in your PATH.
    • If using --system-log, journalctl must be installed.
    • If using a Git URL, git must be installed.
    # Render a single repository
envisaged /path/to/repo --output my_video.mp4

# Render multiple repositories in a directory
envisaged --multi-dir /path/to/repos_folder --template split-quad

# Render system logs (e.g., auth logs from the last 12 hours)
envisaged --system-log auth --system-log-since "12 hours ago"

  7. Use the Envisaged Web service for rendering

    main

    The Envisaged Web service provides a FastAPI-based web interface to trigger video renders of repositories or system logs. It supports three primary modes: single (rendering a single repository), multi (comparing multiple repositories), and system (rendering system logs into a timeline).

    # The service is typically run via the main entrypoint
# which starts a uvicorn server on port 8787.
# Users interact with it via a web browser at http://localhost:8787

  9. Use system log sources for event visualization

    main

    When using the --system-log flag, you can choose from three sources to visualize system events as a timeline:

    • journal: Standard systemd journal entries.
    • kernel: Kernel-specific logs (uses -k flag with journalctl).
    • auth: Authentication-related logs (filters for markers like sudo, sshd, login, etc.).

    Note: When using system logs, you cannot provide a --multi-dir or a specific repo argument. Use --system-log-since to define the starting point (e.g., "24 hours ago") and --system-log-limit to cap the number of entries.

    # Visualize kernel logs since 1 hour ago
envisaged --system-log kernel --system-log-since "1 hour ago" --system-log-limit 1000

  10. Configure Envisaged Templates and Legends

    main

    Envisaged uses template families and legend modes to control the visual output.

    Template Families

    • Core: none, urandom (default), border, neon, sunset, matrix, blueprint, noir.
    • Omarchy core palettes: catppuccin, catppuccin-latte, ethereal, everforest, flexoki-light, gruvbox, hackerman, kanagawa, matte-black, miasma, nord, osaka-jade, ristretto, rose-pine, tokyo-night, vantablack, white.
    • Compare: compare-panel, compare-neon, compare-blueprint, compare-matrix, compare-noir.
    • Split: split-quad, split-vertical, split-triple, split-focus, split-matrix.
    • Relationship: relation-panel, relation-neon, relation-blueprint, relation-noir, relation-sunset.

    Legend Modes

    • --legend auto: Context-aware legend (repo legend for compare/split/relation, service legend for system-log).
    • --legend none: Disable overlays.
    • --legend repos: Show repo legend (best for multi-repo).
    • --legend files: Show top file types (use --legend-limit to control count).
    • --legend actions: Show add/modify/delete totals (repo mode).
    • --legend services: Show top services/users by event count.
    • --legend all: Show repos + file types + actions + services.

  11. Configure Envisaged Sync Modes

    main

    Sync modes control how timelines are aligned, especially useful in multi-repo modes.

    • --sync-timing false: Uses original log timing.
    • --sync-timing true: Uses a normalized unified timeline.
    • --sync-timing smart: Uses a normalized timeline with blank-log pulse anchors.
    • --sync-timing auto: Uses smart mode automatically for compare/split/relation templates in multi-repo mode.

  12. Envisaged CLI Reference

    main

    The CLI follows the pattern: envisaged [OPTIONS] [REPO].

    Arguments

    • REPO: Local git repo path or remote git URL.

    Options

    • --multi-dir <path>: Render all git repos under a directory.
    • --system-log <journal|kernel|auth>: Render system logs as a timeline.
    • --system-log-since "<time expr>": journalctl since selector (default 24 hours ago).
    • --system-log-limit <n>: Max journal entries to ingest (default 5000).