wiki-up

More context is not the same as correct context: project knowledge must stay synchronized.

wiki-up is a milestone reporter that turns a compact project digest into a durable Markdown knowledge-base update, without loading the external vault into the calling session.

The problem

Project knowledge drifts while code changes. A useful update needs the right vault page, conventions, links, history, and publication behavior—but reading an entire personal wiki in every coding session wastes context and increases the chance of recording the wrong thing.

wiki-up keeps the decision close to the project and delegates vault work to a separate context.

What works today

wiki-up is currently a Claude Code milestone reporter with a Pi package:

1. A user or agent decides whether a change is a meaningful milestone.
2. It composes a compact digest: project, headline, up to six bullets, and bare pointers.
3. A separate worker reads the external vault conventions, updates or creates a Markdown page, updates wiki/hot.md and wiki/log.md, and optionally commits and pushes the vault.
4. The caller receives only the validated helper success or failure status.

It does not yet semantically analyze arbitrary Git diffs, find every affected knowledge page, or provide a general conflict-resolution engine. Those are future work, not current behavior.

Architecture

Current project/session
        │
        │ milestone gate + compact digest
        ▼
┌──────────────────────┐       ┌─────────────────────────────┐
│ Claude Code           │       │ Pi /wiki-up                 │
│ Stop hook (automatic) │       │ command (manual)            │
└──────────┬───────────┘       └──────────────┬──────────────┘
           │ Task/subagent                    │ wiki_up_sync tool
           └──────────────────┬──────────────┘
                              ▼
                 ephemeral isolated filing worker
                    │ read conventions + write pages
                    │ scoped commit + optional push
                    ▼
                 external Markdown / Obsidian vault

Future, not shipped:
Git Diff → change detection → knowledge update → human confirmation

Pi quick start

Install the package directly from GitHub:

pi install git:github.com/paipeline/wiki-up

Configure the external vault in Pi's interactive mode:

/wiki-up setup

Then manually report a milestone from any project:

/wiki-up Added release notes and hardened the vault writer

Pi's user entry point is /wiki-up; there is no wiki-up sync shell CLI in this release. The extension also exposes the model-callable wiki_up_sync tool, which should be used only after the milestone gate passes.

To smoke-test a local checkout without installing it, using Pi's temporary local-package mode:

pi --no-extensions -e . -p ""

The Pi extension stores its private configuration at <getAgentDir()>/wiki-up.config.json, with mode 0600. Setup validates the vault directory. Git-backed vaults must use the canonical repository root with a real .git directory; subdirectories and linked worktrees are rejected because filing uses a vault-root lock. An existing local Git vault derives its checked-out branch on every filing and never pulls or pushes; github/gitlab also require the named remote. It never initializes a remote.

Claude Code quick start

The existing Claude installation path remains supported:

git clone https://github.com/paipeline/wiki-up.git
cd wiki-up
bash install.sh

install.sh copies skills/wiki-up to ~/.claude/skills/wiki-up and idempotently registers the Stop hook in ~/.claude/settings.json. Configure it in Claude Code:

/wiki-up setup

The Claude config remains ~/.claude/wiki-up.config.json. For a Git-backed vault, use the canonical repository root with a real .git directory; Claude setup rejects subdirectories and linked worktrees because filing uses a vault-root lock. Existing local Git vaults derive their checked-out branch on every filing and always disable pulls and pushes. To configure by hand:

cp wiki-up.config.example.json ~/.claude/wiki-up.config.json
# edit vaultPath, backend, gitRemote, branch, and autoPush

uninstall.sh removes the installed skill and hook but leaves the config and vault untouched. The .claude-plugin manifest is preserved for plugin-compatible installs; plugin installation alone does not register the automatic Stop hook, so install.sh is the supported Claude path when automatic reporting is wanted.

Setup and usage

Supported backends:

• github / gitlab: commit and optionally push using the vault repository's existing remote and credentials.
• local: write locally; commit when the vault is already a canonical git repository root with a .git directory, but never initialize, pull, or push.

Typical manual use in either client:

/wiki-up setup
/wiki-up Shipped the indexing milestone and documented the new data boundary

The reporter applies a strict gate. Routine WIP, small refactors, typos, and configuration nits are skipped. A filed digest follows this shape:

Project: <name> (<absolute path>)
Headline: <≤12 words>
- <≤12-word fragment>
- <≤12-word fragment>
Pointers: <path> · <sha> · <url>

Privacy and security boundaries

• The compact digest is the only project content sent to the filing worker; source files and diffs are not copied into the vault.
• The configured vault path and backend are validated before vault writes. Missing paths, unsupported backends, absent remote repositories, and invalid configs fail instead of being guessed or initialized.
• The Pi child runs as a separate ephemeral process with --no-extensions --no-skills --no-session --no-prompt-templates --no-context-files --no-approve and only read, write, and bash enabled. Intended vault docs are read explicitly.
• The child receives only an explicit allowlist of runtime paths, Pi/provider authentication, proxy/locale, and Git/SSH variables needed to run Pi and the vault helper. Arbitrary project environment variables are not forwarded.
• Child prompt/config material is created in a private temporary directory with restrictive permissions and removed after completion. shell: false is used, aborts terminate the child, and model-visible output and helper status are capped.
• Claude's deterministic commit helper uses scoped staging, a per-vault lock, and preserves local-only behavior. Push failures leave the local commit in place.
• The filing worker may write to the configured vault by design. Review the package source before installing it; Pi extensions have full system access.
• WIKI_UP_CONFIG can explicitly select a config location for deterministic Claude helper scripts. Without it, existing Claude installs continue using ~/.claude/wiki-up.config.json.

Automatic versus manual behavior

Client	Entry point	Trigger	Filing context
Claude Code	/wiki-up plus installed Stop hook	Automatic: the Stop hook notices a changed commit/tree; Claude applies the milestone gate once	Claude Task/general-purpose subagent
Pi	/wiki-up and wiki_up_sync	Manual: the user invokes /wiki-up; no Stop hook is installed	Ephemeral Pi child with discovery disabled

The Claude hook detects movement; it does not decide that every movement deserves a note. Pi deliberately ships only the manual flow in this slice.

Compatibility

Environment	Status	Installation
Pi package loading from GitHub	Supported	pi install git:github.com/paipeline/wiki-up
Pi temporary local package smoke	Supported	pi --no-extensions -e . -p ""
Claude Code skill + automatic Stop hook	Supported	bash install.sh
Claude plugin manifest	Preserved	.claude-plugin/plugin.json
npm or pi.dev gallery publication	Not claimed	Not part of this change

Limitations

• The current system records milestones; it is not a semantic Git-diff synchronization engine.
• It does not infer all impacted pages or resolve competing edits automatically.
• Pi reporting is manual and requires a configured external vault.
• Git-backed vaults must be configured at the canonical repository root with a real .git directory; subdirectories and linked worktrees are unsupported.
• Remote backends require a pre-existing git repository and named remote; network/authentication problems can still make a push fail after a local commit.
• Filing quality depends on the compact digest and the worker model following the vault's conventions.

Roadmap

1. Detect meaningful changes from Git diffs without treating every changed line as knowledge.
2. Suggest affected pages and show the proposed knowledge update.
3. Add explicit human confirmation before applying updates.
4. Add conflict-aware reconciliation for competing page edits.

The roadmap is intentionally separate from the milestone reporter shipped here.

Development and tests

This repository has zero runtime dependencies. Pi supplies the extension API and the package declares them as peers.

Run the focused hermetic extension harness through Pi:

pi --no-extensions -e tests/wiki-up-extension.test.ts -p ""
bash tests/test-scripts.sh

Validate metadata and existing scripts:

python3 -m json.tool package.json >/dev/null
python3 -m json.tool .claude-plugin/plugin.json >/dev/null
python3 -m json.tool .claude-plugin/marketplace.json >/dev/null
python3 -m json.tool wiki-up.config.example.json >/dev/null
bash -n install.sh uninstall.sh skills/wiki-up/scripts/*.sh
python3 - <<'PY'
from pathlib import Path
compile(Path("skills/wiki-up/scripts/wiki-up-hook.py").read_text(), "wiki-up-hook.py", "exec")
print("python syntax ok")
PY
pi --no-extensions -e . -p ""

Do not publish to npm or claim a gallery listing as part of local development.

License

MIT