{"id":51168380,"url":"https://github.com/yhyzgn/loom","last_synced_at":"2026-06-26T22:01:43.547Z","repository":{"id":365383963,"uuid":"1271858447","full_name":"yhyzgn/loom","owner":"yhyzgn","description":"Personal single-user Git-backed sync hub for AI agent harness configs, hooks, prompts, skills, and timers.","archived":false,"fork":false,"pushed_at":"2026-06-24T09:22:58.000Z","size":183,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-24T11:17:20.356Z","etag":null,"topics":["agent-config","ai-agent","claude","codex","config-sync","dotfiles","gemini","hooks","personal","single-user"],"latest_commit_sha":null,"homepage":"https://github.com/yhyzgn/loom","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yhyzgn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-17T04:32:14.000Z","updated_at":"2026-06-24T09:23:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yhyzgn/loom","commit_stats":null,"previous_names":["yhyzgn/loom"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/yhyzgn/loom","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yhyzgn%2Floom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yhyzgn%2Floom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yhyzgn%2Floom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yhyzgn%2Floom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yhyzgn","download_url":"https://codeload.github.com/yhyzgn/loom/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yhyzgn%2Floom/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34834415,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-26T02:00:06.560Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-config","ai-agent","claude","codex","config-sync","dotfiles","gemini","hooks","personal","single-user"],"created_at":"2026-06-26T22:01:40.165Z","updated_at":"2026-06-26T22:01:43.536Z","avatar_url":"https://github.com/yhyzgn.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# loom\n\n[中文说明](README.zh-CN.md)\n\n`loom` is a small, personal configuration hub for synchronizing global AI-agent / coding-agent harness settings across your own machines.\n\nIt keeps a Git-backed copy of selected agent configuration files, installs startup / exit hooks where supported, adds command shims for common CLIs, and runs a periodic timer so local safe configuration changes can be pushed and pulled across machines.\n\n## 1. Scope and warning\n\n### 1.1 Single-user only\n\n`loom` is designed for **one person syncing their own machines**.\n\nIt is **not** a team configuration-management system. Do not use one shared `loom` repository for multiple people unless you redesign the trust, conflict, and secret-handling model yourself.\n\nWhy single-user only:\n\n- global agent prompts and hooks are highly personal and machine-specific\n- different users may have different model providers, auth methods, red lines, memory files, and MCP servers\n- hook scripts execute locally and should not be accepted from other people casually\n- Git conflicts in global config files are much easier to reason about for one user than for a team\n\n### 1.2 Fork before use\n\nIf you want to use this project, **fork it to your own account first**.\n\nRecommended setup:\n\n1. fork this repository\n2. make the fork private if it contains your personal agent preferences\n3. clone your fork on each machine\n4. run `loom install` on each machine\n\nDo not point your machines at someone else's live config repository.\n\n### 1.3 Do not store secrets\n\n`loom` is intended to sync configuration, prompts, skills, hooks, and similar text assets. It is not a secret manager.\n\nThe repository excludes common secret-bearing files such as:\n\n- auth files\n- API key files\n- token files\n- credential files\n- OAuth files\n- `.env` files\n- session/history/cache databases\n\nStill, you should review your fork before pushing it to any remote.\n\n## 2. What loom syncs\n\n`loom` syncs a curated set of global harness configuration files described in:\n\n```text\nconfig/manifest.json\n```\n\nTypical managed content includes:\n\n- global prompts / memory files\n- harness settings files that do not contain secrets\n- skill directories\n- persona files\n- hook scripts\n- markdown rule files\n\nTypical local-only content includes:\n\n- provider API keys\n- auth tokens\n- OAuth credentials\n- local model/provider endpoints if sensitive\n- runtime sessions, logs, caches, history, and databases\n\n## 3. How synchronization works\n\n`loom sync` performs a two-way Git-backed sync cycle. The key idea is that each machine keeps its own local harness directories, while the `loom` checkout acts as the portable Git-backed hub.\n\n### 3.1 Architecture overview\n\n```mermaid\nflowchart LR\n  subgraph M1[Machine A]\n    A1[Harness config dirs\u003cbr/\u003e~/.codex, ~/.gemini, ~/.claude, ...]\n    A2[Loom checkout\u003cbr/\u003e~/Projects/neo/pub/loom]\n    A3[Hooks / shims / timer]\n  end\n\n  subgraph R[Private Git remote]\n    R1[(Your fork\u003cbr/\u003esingle-user repo)]\n  end\n\n  subgraph M2[Machine B]\n    B1[Harness config dirs\u003cbr/\u003e~/.codex, ~/.gemini, ~/.claude, ...]\n    B2[Loom checkout\u003cbr/\u003e~/Projects/neo/pub/loom]\n    B3[Hooks / shims / timer]\n  end\n\n  A3 --\u003e|trigger loom sync| A2\n  A1 --\u003e|export safe managed files| A2\n  A2 --\u003e|apply managed files| A1\n  A2 \u003c--\u003e|pull / push| R1\n  R1 \u003c--\u003e|pull / push| B2\n  B3 --\u003e|trigger loom sync| B2\n  B1 --\u003e|export safe managed files| B2\n  B2 --\u003e|apply managed files| B1\n\n  S1[Local-only secrets\u003cbr/\u003etokens, API keys, credentials] -. excluded .- A2\n  S2[Local-only secrets\u003cbr/\u003etokens, API keys, credentials] -. excluded .- B2\n```\n\n### 3.2 `loom sync` sequence\n\n```mermaid\nflowchart TD\n  A[Start loom sync] --\u003e B[Export safe managed files from local harness dirs]\n  B --\u003e C[Commit local capture when files changed]\n  C --\u003e D{Git origin configured}\n\n  D --\u003e|Yes| E[Pull remote updates with rebase and autostash]\n  D --\u003e|No| F[Skip remote pull]\n\n  E --\u003e G[Apply loom repo config to local harness dirs]\n  F --\u003e G\n\n  G --\u003e H[Install or repair hooks and clean legacy shims]\n  H --\u003e I[Commit hook wiring when changed]\n  I --\u003e J{Git origin configured}\n\n  J --\u003e|Yes| K[Push local commits to private remote]\n  J --\u003e|No| L[Skip remote push]\n\n  K --\u003e M[Run loom doctor]\n  L --\u003e M\n  M --\u003e N[Sync complete]\n```\n\n### 3.3 Trigger flow\n\n```mermaid\nflowchart TD\n  Start[Trigger] --\u003e Kind{Trigger source}\n\n  Kind --\u003e|Manual| Manual[loom sync]\n  Kind --\u003e|Harness startup| HookStart[loom hook --phase start]\n  Kind --\u003e|Harness normal exit| HookExit[loom hook --phase exit]\n  Kind --\u003e|Periodic timer| Timer[loom hook --phase timer]\n\n  Manual --\u003e Sync[Run sync cycle]\n  HookStart --\u003e Sync\n  HookExit --\u003e Sync\n  Timer --\u003e Sync\n\n  Sync --\u003e Export[Export safe local managed files]\n  Export --\u003e Commit1[Commit local capture]\n  Commit1 --\u003e Pull{Git origin?}\n  Pull --\u003e|yes| Rebase[Pull with rebase/autostash]\n  Pull --\u003e|no| LocalOnly[Skip remote pull/push]\n  Rebase --\u003e Apply[Apply repo config to harness dirs]\n  LocalOnly --\u003e Apply\n  Apply --\u003e Repair[Repair hooks and clean legacy shims]\n  Repair --\u003e Commit2[Commit wiring changes]\n  Commit2 --\u003e Push{Git origin?}\n  Push --\u003e|yes| RemotePush[Push to private remote]\n  Push --\u003e|no| DoneLocal[Local sync complete]\n  RemotePush --\u003e Doctor[Run doctor]\n  DoneLocal --\u003e Doctor\n  Doctor --\u003e Done[Done]\n```\n\n### 3.4 Step-by-step behavior\n\n`loom sync` performs these concrete steps:\n\n1. export safe local managed files into the loom repository\n2. commit local changes if any\n3. pull remote changes with rebase / autostash when a Git origin exists\n4. apply repository config back to local harness directories\n5. install or repair hooks and clean up legacy command shims\n6. commit hook wiring changes if any\n7. push to remote when a Git origin exists\n8. run `loom doctor`\n\nIf no Git remote is configured, local export/apply still works, but cross-machine sync will not happen.\n\n## 4. Installation\n\n### 4.1 Clone or fork\n\nUse a persistent checkout. The default expected location is:\n\n```text\n~/Projects/neo/pub/loom\n```\n\nExample:\n\n```bash\nmkdir -p ~/Projects/neo/pub\ncd ~/Projects/neo/pub\ngit clone \u003cyour-private-fork-url\u003e loom\ncd loom\n```\n\n### 4.2 Install on the current machine\n\nPreferred install uses the platform executable built by GitHub Actions. Download the artifact/release asset for your OS, put it in this checkout's `bin/` directory, and name it `loom` on Linux/macOS or `loom.exe` on Windows. Then run:\n\n```bash\n# Linux/macOS\n./bin/loom install\n\n# Windows PowerShell\n.\\bin\\loom.exe install\n```\n\nFor development on Linux/macOS you can still run the Python source at `bin/loom`; Windows should use `loom.exe` because the source file has no native Windows launcher semantics.\n\nAfter the first install, new shells should be able to run:\n\n```bash\nloom doctor\n```\n\n`loom install` performs the local machine setup:\n\n1. installs the current platform executable into the user executable path, default `~/.local/bin/loom` on Unix or `%LOCALAPPDATA%\\Programs\\loom\\bin\\loom.exe` on Windows\n2. installs harness startup / exit hooks where configured\n3. leaves real harness CLIs untouched; same-name command shims are disabled by default\n4. installs a periodic timer\n5. runs `loom doctor`\n\n### 4.3 Configure the remote\n\nFor cross-machine sync, configure your private remote:\n\n```bash\ncd ~/Projects/neo/pub/loom\ngit remote add origin \u003cyour-private-fork-url\u003e\ngit push -u origin main\n```\n\nOn the next machine, clone the same fork and run:\n\n```bash\nloom install\nloom sync\n```\n\n## 5. Automatic sync layers\n\n`loom` uses multiple sync triggers because no single hook mechanism is reliable across every harness.\n\n### 5.1 Harness hooks\n\nFor harnesses that support hooks, `loom` writes startup and exit sync hooks.\n\nExamples of event types used by supported harnesses:\n\n- `SessionStart`\n- `Stop`\n- `SessionEnd`\n\nTo keep harness startup fast, automatic hook/timer sync is throttled to at most once per local calendar day. After the first successful automatic sync of the day, later startup, exit, and timer hooks skip quickly. Manual `loom sync` always runs a full sync.\n\nThe daily throttle state is local runtime state stored under:\n\n```text\nstate/last-auto-sync.json\n```\n\nThis file is intentionally ignored by Git.\n\nFor Codex specifically, `Stop` hooks must return valid JSON on stdout. `loom` therefore installs a JSON-safe Codex Stop hook wrapper: sync logs are redirected to `logs/codex-stop-hook.log`, while stdout returns `{}`. This prevents Codex errors such as `hook returned invalid stop hook JSON output`.\n\nExact support depends on the harness.\n\n### 5.2 Command shims\n\nSame-name command shims are **disabled by default**. `loom` does not move or replace harness CLIs such as `codex`, `gemini`, `claude`, or `opencode`, and it should not put wrapper commands ahead of the real CLIs in `PATH`.\n\nAutomatic sync now relies on native harness hooks where available plus the periodic timer. If you need sync in the middle of a day, run:\n\n```bash\nloom sync\n```\n\nMigration note: older versions created same-name wrapper files under `shims/` and added that directory to shell `PATH`. Current `loom sync`, `loom apply`, `loom install`, and `loom install-shims` automatically remove those legacy wrapper files and remove the old `loom shims` PATH block from `~/.bashrc` and `~/.zshrc`. On another machine that already synced earlier today, run `loom sync` once manually or wait for the next day's automatic sync so the cleanup can be applied.\n\n### 5.3 Periodic timer\n\n`loom install-timer` installs a periodic sync timer.\n\nSupported timer backends:\n\n| OS | Backend |\n| --- | --- |\n| Linux | `systemd --user` timer |\n| macOS | `launchd` LaunchAgent |\n| Windows | Task Scheduler via `schtasks` |\n\nThe timer is a safety net for changes made while a harness is running or for abnormal exits where an exit hook may not run.\n\n## 6. Common commands\n\n```bash\nloom install          # full local machine setup\nloom doctor           # validate managed files and hook config\nloom sync             # run full two-way sync now\nloom export           # export safe local files into the repo\nloom apply            # pull/apply repo files back to local harness dirs\nloom install-cli      # install ~/.local/bin/loom\nloom install-hooks    # install/repair harness hooks\nloom install-shims    # currently a no-op; same-name shims are disabled by default\nloom install-timer    # install/repair periodic timer\nloom timer-status     # show timer status\n```\n\nUseful examples:\n\n```bash\nloom sync\nloom timer-status --platform linux\nloom install-timer --interval-minutes 5\nloom install-cli --cli-mode symlink\n```\n\n## 7. Repository layout\n\n```text\nbin/loom                  # main CLI source for development / Unix fallback\nbin/loom.exe              # optional generated Windows executable, ignored by Git\n.github/workflows/        # CI build for Linux/macOS/Windows executables\nscripts/build.py          # local PyInstaller build helper\nconfig/manifest.json      # managed file manifest and exclusions\nagents/                   # per-harness synced configuration\nshared/                   # shared personas/hooks/assets\nshims/                    # optional shim workspace; not added to PATH by default\ntemplates/                # templates such as Git hooks\nlogs/                     # local logs, ignored by Git\nstate/                    # local state, ignored by Git\n```\n\n## 8. Safety model\n\n`loom` uses several layers to reduce accidental secret syncing:\n\n- manifest-level local-only files\n- exclude globs for token/auth/credential/cache/session files\n- JSON sensitive-key checks during export\n- Git ignore rules\n- a pre-commit secret scanner template\n\nThis is best-effort protection, not a substitute for review.\n\nBefore pushing to a remote, inspect:\n\n```bash\ngit status\ngit diff --cached\ngit grep -n -I -E 'token|api[_-]?key|secret|password|credential|oauth'\n```\n\nIf a file contains secrets, remove it from `managed_files` and add it to `local_only_files` / `exclude_globs` in `config/manifest.json`.\n\n## 9. Conflict handling\n\n`loom` uses Git as the source of truth for cross-machine sync.\n\nThe normal flow uses:\n\n```text\ngit pull --rebase --autostash\n```\n\nIf two machines edit the same managed file differently, Git may require manual conflict resolution. Resolve the conflict in the loom repository, then run:\n\n```bash\nloom doctor\nloom apply\nloom sync\n```\n\nFor best results, avoid editing the same global config on multiple machines at the same time.\n\n## 10. Current assumptions\n\nThis repository currently reflects one user's harness ecosystem and paths. If you fork it, expect to customize:\n\n- `config/manifest.json`\n- harness-specific files under `agents/`\n- hook definitions\n- shims\n- timer interval\n- any global prompt/persona content\n\nThat customization is expected. Treat your fork as your personal agent-config home, not as a universal default.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyhyzgn%2Floom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyhyzgn%2Floom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyhyzgn%2Floom/lists"}