Major Tom Demo

July 21, 2026 · View on GitHub

Major Tom Demo is a privacy-first, local desktop activity journaling prototype inspired by the filter-plan-log design of FOCAL. It combines lightweight activity filtering, selective visual reasoning, task-isolated Markdown memory, and a localhost dashboard.

This repository is an engineering demo, not the paper's experiment runner. The reproduction code lives in Haoran2099/focal, and its derived benchmark artifacts live in the public HaoranYin/desktopbench dataset. See COMPARISON_WITH_FOCAL.md for the exact mapping.

Safety defaults

  • Ollama models run locally by default.
  • File context is restricted to demo_input/.
  • Logs and memories are written below runtime/, which Git ignores.
  • The dashboard binds to 127.0.0.1, accepts only localhost Host headers, and has no cross-origin policy.
  • File mutation endpoints are absent unless --enable-write-api is supplied.

The recorder requests screen-recording, accessibility, and input-monitoring permissions and analyzes the visible desktop. Start with --web-only if you only want to inspect the UI. Read PRIVACY.md before recording.

Platform support

  • macOS: supported recorder and dashboard platform.
  • Windows: experimental recorder support; behavior depends on desktop APIs.
  • Linux: dashboard (--web-only) only for this release.

Python 3.10-3.12 and a separately installed Ollama are required.

Install

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
cp config.example.json config.json
ollama pull qwen3:8b
ollama pull qwen3-vl:8b
ollama pull qwen3-embedding:8b

On Windows, activate the environment with .venv\\Scripts\\activate.

Run

Dashboard only, with no screen capture:

major-tom --web-only

Recorder and dashboard:

major-tom

Recorder without the dashboard:

major-tom --no-web

To opt in to dashboard file creation, editing, deletion, and config reload:

major-tom --web-only --enable-write-api

Open http://127.0.0.1:8000. Do not expose this service through a public interface or reverse proxy.

macOS permissions

When prompted, allow the terminal application under System Settings → Privacy & Security → Screen Recording, Accessibility, and Input Monitoring. Restart the terminal after changing permissions. Keep confidential windows closed during demos.

Verify and uninstall

python -m pip install -e ".[dev]"
python -m pytest
python -m compileall -q src

Stop the process, remove the virtual environment, and optionally remove local runtime data:

rm -rf .venv runtime/Record runtime/Memory

config.json, runtime data, and model data are local artifacts and are never required in commits.

中文快速开始

本项目默认使用本地 Ollama，并把文件读取限制在 demo_input/。先复制 config.example.json 为 config.json，再运行 major-tom --web-only 检查 界面。真正录屏前请在 macOS 授予屏幕录制、辅助功能和输入监测权限，并关闭 邮件、聊天、密码管理器等敏感窗口。Web 文件修改功能默认关闭，只有显式添加 --enable-write-api 才会启用。

Citation and license

If this demo helps research derived from FOCAL, cite the paper using CITATION.cff. Code is released under the MIT License.