Technical Briefing: whoami

The Problem

whoami-wiki/whoami (525 stars) is a collection of 4 self-contained projects totaling 316 files that transform personal digital archives—photos, chats, location history, transactions, social media exports—into a private encyclopedic wiki about your life. The repository contains no single unifying architecture; rather, it is a portfolio of CLI, desktop, web, and evaluation tools sharing some dependency infrastructure but operating independently.

What This Does

The repository delivers four distinct products:

  • web (169 files, 46 code files): A Next.js-based interface with docs, blog, and site components. Entry points include web/components/navbar.tsx and web/components/docs-sidebar.tsx, both flagged for deep nesting (max indentation depth 8).
  • cli (39 files, 32 code files): A command-line tool for managing the wiki. Core entry point is cli/src/index.ts, which reaches 142 functions via main. Commands span auth, import, export, snapshot, and task management, all resolved from cli/src/commands/.
  • evals (47 files, 29 code files): An evaluation harness for LLM grading. Entry point evals/src/index.ts reaches 3 functions via print_scores. The grading pipeline lives in evals/src/graders/index.ts, which reaches 48 functions and contains high branching density (16 branch points over 54 lines in evals/src/runner/e2e.ts).
  • desktop (47 files, 14 code files): An Electron-based desktop client. Entry point desktop/src/main.ts:121 (launchWiki) reaches 17 functions. Integrates a PHP server (desktop/src/php-server.ts) for local MediaWiki serving.

How It Is Wired

Execution originates at the CLI: cli/src/index.ts:100 (main) is the primary entry point, reaching 142 functions and called from 1 place. The call graph shows cli/src/index imports cli/src/wiki-client (20 dependents, 1 import, instability 0.05) and cli/src/errors (20 dependents, 0 imports, instability 0), making the latter a stable hub with wide blast radius. cli/src/output is similarly depended on by 18 modules.

Network effects are traced: main -> login [network via this.client.get] and launchWiki -> autoLogin [network via net.fetch]. File operations are performed by desktop/src/setup.ts, which makes outbound network calls and performs cryptographic/secret-generating operations (isFirstRun, runSchemaUpdate).

Duplicated code is prevalent: 203 repeated 6-line blocks across 55 files, concentrated in cli/scripts/release.sh, desktop/scripts/release.sh, cli/src/commands/changes.ts, and cli/src/commands/task.ts. Cognitive load is elevated in oversized files: evals/src/runner/e2e.ts (954 lines), web/components/app-window.tsx, and web/components/desktop-scene.tsx.

How To Use It

Setup

The repository uses pnpm as package manager. Install with:

pnpm install

Each project has its own package.json and pnpm-lock.yaml. No root-level workspace configuration is present; workspaces are declared in desktop/pnpm-workspace.yaml and cli/pnpm-lock.yaml.

Configuration

Environment variables are expected in .env.example located at evals/.env.example. No global .env or secrets file is committed; credential management is handled via cli/src/auth.ts (resolveCredentials, saveCredentials, removeCredentials). The desktop app stores local settings via desktop/src/setup.ts (runSchemaUpdate, refreshLocalSettings).

Running it

  • CLI: pnpm run <command> from cli/ directory. Available commands are defined in cli/package.json scripts and resolved through cli/src/index.ts.
  • Desktop: Launch via pnpm start from desktop/ or build with pnpm run build.
  • Evals: Run from evals/ with pnpm test or pnpm start, depending on configuration in evals/package.json.

No Dockerfile is present. No Makefile or root-level build script exists.

Real-World Use

A researcher exporting chat logs and location history can use the CLI to import these archives into a local wiki:

whoami import /path/to/exports
whoami snapshot --capture-photos
whoami export --format md > wiki.md

The resulting markdown can be served locally via the desktop app or published to a private instance. The evals suite can grade LLM responses against expected outputs for the wiki's content generation prompts.

Code Health & Issues

Static analysis identified 10 findings (0 critical, 3 high, 5 medium, 2 low):

  • [HIGH] Pin third-party GitHub Actions to commit SHA - .github/workflows/ci.yml and release.yml use @vN syntax for pnpm/action-setup@v4 and softprops/action-gh-release@v2. A tag can be moved, so actions running with secrets may execute with unexpected versions.
  • [HIGH] Upgrade the pinned dependency carrying a published advisory - electron@33.4.11 has CVE-2026-34774 (high). The pinned version is the one that installs, so this advisory describes the deployment.
  • [HIGH] Make CI invoke the test suite it has - 10 test files exist but no test command appears in any workflow. A green check that never executed an assertion is worse than no check.
  • [MEDIUM] Declare least-privilege permissions for GITHUB_TOKEN - 1 workflow declares no permissions top-level key, so the token inherits repository defaults allowing push and release minting.
  • [MEDIUM] Enable Dependabot or Renovate - 4 manifest files exist with no update bot configured. Without a bot, published advisories remain unpatched.
  • [MEDIUM] Gate pull requests on a dependency vulnerability scan - no dependency-review-action or osv-scanner step is present in CI.
  • [MEDIUM] Expand the README - 260 bytes of README for 123 code files. No install, run, or worked example is documented.
  • [MEDIUM] Set persist-credentials: false on checkout - checkout retains the token for all later steps; a malicious postinstall script could read pushable credentials.
  • [LOW] Set timeout-minutes on workflow jobs - 3 workflows declare no job timeout, risking overlap on a two-hourly schedule.
  • [LOW] Add convention files - missing .editorconfig, .gitattributes (with text=auto eol=lf), and formatter config.

The Bottom Line

The repository delivers four functional projects—CLI, desktop, web, and evals—that successfully personalize a wiki from private data. The codebase is structurally sound with no critical issues, but duplicated logic, outsized files, and outdated/insecure dependencies demand attention. It is best suited for individual or small-team users who need to turn personal archives into a searchable encyclopedia and are willing to maintain the associated tooling.