How Logseq proxies work
+A proxy keeps a source page’s name and content in another garden. The page discloses its source. Sync brings along the definitions and tools needed to use it.
+The useful promise: edit the source, preview the import, then refresh the destination. Each destination can keep its own publication settings while sharing the source’s content.
The guide describes the merged implementation at the commit above. PR #199 — preserve proxy identity across worktrees is merged and included here, explained under parallel agents.
+The page-to-page relationship stays visible
+A source named GitP/A/Session/24/12/04-Wed becomes a destination page with the same name. Each garden has its own Markdown file. The destination’s frontmatter says where the source lives and when it was copied.
Page body + frontmatter
Entity definitions
Declared tools + local assets
Resolve source
Build import plan
Check ownership + changes
Same page name
Proxy source properties
Copied definitions + tools
.logseq-proxy/manifest.json accompanies the imported files: source identities, script ownership, last imported script hashes, and declarations for onward imports.logseq-proxy-url:: logseq://graph/logseq-encode-garden?page=GitP%2FA%2FSession%2F24%2F12%2F04-Wed
+logseq-proxy-codeforge-url:: https://github.com/codekiln/logseq-encode-garden/blob/main/pages/GitP___A___Session___24___12___04-Wed.md
+logseq-proxy-last-sync-date:: [[2026-10-07]]Example after a refresh from main. The Logseq URL opens the source graph; the forge URL identifies its repository and source file; the date records the sync day. The membership [[Logseq/Entity/Proxy/Page]] is added beside the page’s existing entity types.
Copying allows Logseq to query and display the content locally. The destination can be committed, cloned, published, and read while the source garden is closed. Sync runs when invoked; it does not continuously watch either garden.
+ +From a source edit to a reviewed import
+Preview and apply use the same planning algorithm. The preview prints the planned files and property changes. Applying runs a fresh plan and then checks that the files have not changed while that plan was being built.
+ +Add a page that lives in another garden
Choose a local source graph, a destination graph, and the exact logical page name.
Supply --source for the first import. Both graph roots must contain pages/ and logseq/. The task reads local files; it does not clone or fetch the source.
Read the page’s logseq-entity links, visit their definitions, follow entity-tasks and task-dependencies, and copy the declared task reference pages and mapped implementation files. A visited set prevents repeated traversal of shared or cyclic definitions and task dependencies. Add --follow-embeds to include embedded pages recursively; ordinary wikilinks are not followed.
Plan the new proxy page, proxy membership, source URLs, sync date, supporting files, and manifest. Copy linked ../assets/… files when present. Missing local assets or embedded pages produce warnings; missing required tasks or implementations stop the import.
A destination page with the same name and no proxy URL is a collision. An existing script without an ownership record is a collision too—even if its contents match. Competing source claims stop application.
Rerun with --apply. The task locks the destination graph, checks the plan’s file preconditions, stages replacements, and saves rollback information before replacing files.
Review the destination diff. Commit the proxy pages, imported task files, copied assets allowed by the garden’s asset policy, and manifest together. Sync writes files; it does not stage, commit, push, or merge.
Refresh a proxy after its source changes
Edit the source garden, then preview from the destination. Keep the local source checkout current before syncing.
The existing proxy’s forge URL locates its registered ghq repository and graph folder. Without a forge URL, the Logseq graph registry can resolve the graph name. Supply --source when discovery is ambiguous. The forge URL does not fetch or switch the local checkout to its named branch.
Source-owned properties are added, updated, or removed to match the source. Existing destination tags and keys named by source entity definitions’ entity-proxy-destination-properties retain their destination values. An absent destination-owned property stays absent on refresh. Proxy metadata is rewritten by sync.
The source body replaces the entire destination body. Referenced local assets are copied over their destination paths. A local change to a proxy body or asset made before this invocation is not protected by the script hash check.
Compare each imported script’s current contents and file mode with the manifest’s last imported hash and mode. If they still match, accept the new source version. A locally edited or deleted imported script stops application. Scripts removed from upstream mappings are retained and reported as cleanup candidates.
Apply the reviewed changes and commit the destination files with the updated manifest. A same-day refresh with identical inputs can produce no changes; a later-day refresh updates the sync date even if the source content is unchanged.
# Preview a first import from the registered source checkout
+mise run logseq:entity:proxy:page:sync \
+ --source /path/to/logseq-encode-garden \
+ --destination /path/to/gitpa/gitp-garden \
+ --page 'GitP/A/Session/24/12/04-Wed'
+
+# Repeat that command with --apply after reviewing the preview.
+# For later previews, --source can be omitted when discovery succeeds.
+mise run logseq:entity:proxy:page:sync \
+ --destination /path/to/gitpa/gitp-garden \
+ --page 'GitP/A/Session/24/12/04-Wed'Edit shared content at its source. Proxy page bodies and copied assets are replaced on refresh. Keep local publication values in destination-owned properties. The script edit protection does not extend to every copied file.
Code: destination-owned properties, source discovery, companion traversal and ownership, application and rollback.
+Different sources can share one destination
+There is no single-source setting for a destination. Each import supplies or resolves its own source, and each page has its own proxy URL. The manifest distinguishes sources by repository + graph path within that repository.
+Garden A / Music
Repository: github.com/example/music
Graph folder: .
Page: Music/Session/A
Garden B / Reading
Repository: github.com/example/reading
Graph folder: garden
Page: Book/Notes/B
One destination garden
pages/Music___Session___A.md ← Garden Apages/Book___Notes___B.md ← Garden BIllustrative names. Each page keeps its own source metadata. A manifest page record includes the source repository, graph folder, and logical page name.
Different names and compatible claims
Independent pages and script paths can coexist. Re-importing a shared definition or script from the same repository and graph is recognized as the same source ownership.
The same destination claimed by another source
The graph has one file per logical page name. Another garden cannot silently replace that page. Two source scripts cannot claim the same destination path, even if their contents happen to match.
Entity definitions share this page namespace too. If Music and Reading both supply a definition named Logseq/Entity/Book, importing from the second source stops even when the definition text matches. A definition proxied through an intermediate garden is claimed under that immediate source garden’s identity; the importer does not unify claims by their ultimate upstream origin. Multiple gardens work when all imported page and script claims are compatible, not merely when the requested note names differ.
The source tuple lets nested graph folders coexist too. For Git repositories with an origin, identities use repository addresses and relative paths. Without an origin, the code falls back to an absolute local path; that case does not have the same portability guarantee.
Code: repository identity and file and page claims. Page frontmatter adds checks for the Logseq source name and forge repository.
+Why a manifest exists
+The page already says what it proxies. The extra information needed for safe script updates is what was imported last time. Today’s source and destination files alone cannot distinguish an upstream change from an edit made locally after import.
+The same ownership records could be expressed as attributes on task reference pages. A separate JSON file groups the file mappings, modes, and historical hashes without adding operational properties to every visible page. That is a storage choice; the safety comes from retaining and checking the import baseline.
+Remember the baseline
The source script was version A. Sync copied A into the destination and recorded A’s hash and file mode in the manifest.
Compare before replacing
If the destination still matches A, sync can replace it with upstream version B. If the destination is locally edited version C, sync stops for review.
| Manifest section | Information retained | Role in the algorithm |
|---|---|---|
files | Source tuple, last imported hash, file mode | Protects imported implementation files from local edits and competing source ownership. |
pages | Repository, graph folder, logical name | Rejects a later claim by a different source garden. |
tasks | Task identity and source-to-destination mapping | Finds imported task files when this proxy garden becomes a source for another garden. |
declarations | Entity/task properties and source link | Supplies saved declarations for onward imports from proxy pages. |
imports | Source graph, requested page, accumulated script paths | Reports removed upstream script mappings as cleanup candidates. |
The manifest has more authority than an index. When a source page is itself a proxy, saved declarations override its entity/task properties during companion discovery. Editing those properties on the proxy page can therefore disagree with what an onward import uses. The declarations are refreshed by sync, but the implementation does not independently reconcile arbitrary manual edits between syncs.
This declaration cache was introduced while re-sync preserved destination frontmatter broadly. Re-sync now refreshes source-owned properties, but the cache still exists. Keeping frontmatter authoritative and limiting stored state to ownership, path mappings, and historical hashes is a possible simplification; it is not the current algorithm.
+The manifest is written with the same staged update and recovery journal as the imported files. Hand-editing hashes to acknowledge a local change would remove the evidence used by the edit check. Deleting the manifest also loses ownership: existing imported scripts then appear unowned and a repeat import stops.
+Code: manifest validation and saved declaration precedence, onward task path resolution. History: PR #186 — companion task contract and explanation of chained imports.
+Commit the import as one change
+The destination should carry the files someone needs to read its pages and safely refresh its imported tools after cloning. A local server process and recovery scratch files serve a different purpose.
+| File or state | Git treatment | Current behavior |
|---|---|---|
pages/*.md | Commit imported pages and definition/task reference pages. | Written by sync; proxy properties live in these files. |
mise-tasks/… | Commit the imported entrypoint, helpers, and mapped documentation; preserve executable modes. | Written only from explicit task-files mappings. Root Mise configuration is not copied automatically. |
assets/… | Follow the destination’s asset policy; include copied assets that belong in Git. | Local ../assets/ links trigger copying. HTTPS media remains a URL and is not downloaded. |
.logseq-proxy/manifest.json | Commit alongside imported files. | This garden and Gitpa do not ignore it. It holds ownership history needed by the next import. |
.logseq-proxy-transaction/ | Keep local; never commit a rollback journal. | Created only while applying; deleted after success or rollback. An interrupted run can leave it behind. Neither garden currently has an explicit ignore rule for this directory. |
| Python caches, editor backups, worktrees | Ignore as local generated state. | The garden ignores __pycache__/, *.pyc, Logseq backup/recycle directories, and dot-prefixed worktree locations. |
| Docs preview server | Commit its HTML and launcher; keep the running process local. | The docs task creates no build output, log file, or saved browser state. |
Sync does not change .gitignore. After applying, use git status and git diff, then stage the import’s specific files. If an interrupted transaction appears, recover it before staging:
mise run logseq:entity:proxy:page:sync \
+ --destination /path/to/destination-garden --recover
+
+# Review again after recovery; then run a fresh preview.Code: recovery and temporary transaction directory. Ignore rules: garden .gitignore and Gitpa PR #12 .gitignore.
+Parallel work needs an integration plan
+Sync protects a destination during application. Git combines changes made in different worktrees later. Those are separate operations, with separate kinds of conflict.
+Lock, then check what changed
Cooperating sync processes serialize application using a lock on the destination graph directory. After obtaining the lock, a plan must still match the source contents and the destination contents and modes it read. A stale plan stops; rerun it.
Logseq, editors, and other programs do not necessarily honor this lock. It does not freeze either garden against arbitrary external writes.
Isolation, then Git integration
Each agent has its own destination files and manifest. Independent page edits can merge cleanly, but imports may also touch shared definitions, shared scripts, and the same JSON manifest. The runtime lock does not coordinate separate worktrees.
The current design does not guarantee conflict-free merges. Sorting manifest keys makes output consistent, but adjacent insertions can still conflict in Git. A clean textual merge also needs semantic review: a manifest and its scripts must describe the same imported versions.
Give agents distinct source pages or namespaces. Make shared entity-definition changes in a coordinated change so each consumer imports the same definitions.
Bring source changes together, then refresh the destination against that combined source. Prefer one agent to perform the final destination sync, especially when the imported tools or definitions overlap.
If branches already contain independent imports, resolve source/page decisions and build a consistent destination from the common pre-import destination state. Reapply the required imports sequentially. Review the resulting files and manifest together rather than guessing conflicting hashes.
Run a fresh preview and check both the page diff and imported script ownership. A same-day repeat with identical inputs should be unchanged. Commit and merge the reviewed set.
Why recompute from a consistent baseline?
The sync checks that existing imported scripts match their manifest hashes before it updates them. Combining a manifest from one branch with a script from another can fail that check. Reapplying imports from a common, consistent baseline lets the task produce matching ownership records. This is an integration workflow, not a built-in Git conflict resolver.
Source worktrees retain the registered graph identity
Sync can read files from a selected source worktree while deriving the graph name from the primary checkout at the same repository-relative graph path. An issue-named worktree therefore keeps the registered graph's Logseq identity.
PR #199 — preserve proxy identity across worktrees is merged. Forge links identify the chosen worktree branch, or its commit when detached; normal imports from the primary checkout use the remote default branch. After upstream changes merge, refresh from the registered source checkout to update source links. Ownership identities use the repository and graph path, so changing a branch does not create a new ownership claim.
A simplified illustration of the documented checks. This control does not read or modify a graph.
Code: locking and file preconditions and ownership records and sorted JSON.
+See what a proxy discloses
+Logseq can query the stored properties even when the display configuration hides them. In Gitpa PR #12, :block-hidden-properties also removes the proxy keys from the clickable property editor. The Markdown file contains the full frontmatter.
# Find proxy files, regardless of Logseq’s display settings
+rg -n '^logseq-proxy-url::' pages/ --glob '*.md'
+
+# Inspect the file from the December episode example
+sed -n '1,12p' pages/GitP___A___Session___24___12___04-Wed.mdThat page’s properties are visible in Gitpa PR #12’s checked-in episode file. A presentation-only hiding approach could leave the properties accessible while editing; the current Gitpa configuration does not provide that behavior.
+Open the guide or follow the code
+mise run logseq:entity:proxy:page:docs:serve
+
+# Choose another local port or keep browser selection manual
+mise run logseq:entity:proxy:page:docs:serve --port 8768 --no-openThe docs task serves this directory on 127.0.0.1 and opens the default browser unless --no-open is supplied. Stop it with Ctrl-C. This HTML also works when opened directly from disk.
Executable implementation
sync entrypoint
page planning and transaction logic
companion tasks and manifest logic
Garden definitions
Proxy Page
Proxy sync task contract
Mise task mapping contract