AgentWiki Local Sync

Always use the one-time, exact-version connection instruction generated by AgentWiki. It is the recommended installation path for the intended server and Agent identity. No separate wiki tool init, remote model key, or background daemon is required.

@neomei/agentwiki-local-sync lets a local coding agent use AgentWiki and prepare knowledge from a local repository or document folder through one stdio MCP gateway named agentwiki. It installs the gateway plus a shared Agent Skill. Source files, model providers, and the organization step stay on the local machine; AgentWiki only receives the prepared knowledge envelope after confirmation.

Prerequisites

• Node.js 24 or 26
• Python 3.10 or later (only required for PDF/DOCX conversion)
• npx
• A supported local client (Codex, Claude Code, or OpenCode)
• An AgentWiki-generated, one-time installation instruction and its unexpired install code

doctor checks the supported Node line (24 or 26), AgentWiki connectivity, the Agent state, Space grant, effective scopes, plugin version, and local dependencies. For CodeGraph it only reports independent discovery, diagnostic version, required/optional capability status, and an optional source index status (doctor --source-path <path>). It never installs or upgrades CodeGraph. On the first document scan, local-sync creates a private Python environment under ~/.agentwiki/runtime/ and installs the exact Microsoft MarkItDown version automatically; it does not modify the system Python environment or require an interactive init.

One AgentWiki gateway

The installer creates or updates exactly one MCP entry named agentwiki. The gateway exposes three stable tool families:

• wiki_* — remote AgentWiki pages, graph, sources, reviews, and memory
• local_* — local source inspection and artifact access
• knowledge_* — combined scan, preview, sync, pull, and conflict workflows

The gateway bridges to the server internally. Users and Agents must not register a second direct /api/mcp connection or a credential-specific MCP name.

CodeGraph is a separately installed scanner with its own version and lifecycle. AgentWiki is version-decoupled: it reads supported structural scan results, deterministically analyzes them, and decides which generated knowledge may enter an AgentWiki Preview. Do not add a second CodeGraph MCP to AgentWiki.

Resumable connection onboarding (candidate)

The new finite-process flow is available in this 0.10.0 source candidate. It requires the matching server with agent-connect, /onboard/spaces, and /onboard/device/renew support. The public 0.9.1 release does not contain these commands; run the built candidate below until a coordinated release supplies the new pinned version.

node dist/cli.js onboard start --server https://agentwiki.quukk.com/api --client codex --protocol json
node dist/cli.js onboard status --session <uuid> --protocol json
node dist/cli.js onboard continue --session <uuid> --reply-file /absolute/reply.json --protocol json
node dist/cli.js onboard continue --session <uuid> --protocol json

Each command exits with one JSON object. Start checks local configuration and returns authorization_required with authorizationUrl, expiresAt, and retryAfterMs. Ask the user to authorize in the browser, then run continue after that delay. Status is strictly read-only and cannot poll, install, scan, or reveal credentials.

After authorization, input_required contains requestId, replyExpiresAt, and eligible spaces: [{id, name}]. Present the names and ask for the Space, Agent name, and reader, editor, or publisher role. Write one of these private JSON replies using a file API (POSIX mode 0600), without interpolating user text into shell commands:

{"requestId":"<current-request-id>","values":{"spaceMode":"existing","spaceId":"<selected-id>","agentName":"My Agent","role":"editor"}}

For a new Space use spaceMode: "create" and spaceName instead of spaceId. Do not add sourcePaths, source type, analysis mode, or client type to the reply.

The next confirmation_required result contains the Space/role/configuration preview and an opaque planHash. After explicit user confirmation, create a fresh private file:

{"requestId":"<current-request-id>","confirmed":true,"planHash":"<exact-returned-hash>"}

confirmed: false cancels. Reply files remain on disk; their request IDs are consumed in the durable session, so replay, expired replies, and wrong hashes are rejected. Each continue advances one phase. Continue without a reply while status: "configuration_pending". An error: {code, retryable} preserves the current phase and connection state; inspect it before retrying. authorization_expired can be renewed with continue: approve the new browser URL and confirm again. The server session, plan, and bootstrap idempotency key stay unchanged.

Completion reports separate evidence:

• connectionStatus: "connected" and gatewayVerification: "passed": installation, local gateway MCP handshake, and remote identity/Space access checks passed.
• clientReloadRequired: true, hostVerification: "not_started": reload the actual client's MCP configuration and make a real host tool call to read a known page.
• knowledgeImport: "not_started": no repository scan, read-only pull, or upload ran. Optional import uses existing knowledge_* tools with its own preview and confirmation.

A verification failure after config installation reports connectionStatus: "configured" and keeps the config/credentials for same-session retry. Local session files are private under ~/.agentwiki/onboarding/steps/; never copy their contents into prompts or reports. Concurrent continuation is rejected with SESSION_BUSY; crashed process locks recover on the next command. Changed client configuration requires a fresh confirmation.

Onboarding (0.10.0)

Use the pinned onboarding command to complete the full self-service flow:

npx --yes @neomei/[email protected] onboard \
  --server https://agentwiki.quukk.com/api \
  --protocol ndjson

The onboarding flow performs web Device Authorization, collects parameters via NDJSON, confirms a unified plan, and installs a single agentwiki gateway MCP. Reader completes with a read-only pull after gateway verification and never calls the write-sync path. Editor and Publisher run the first local scan and sync after explicit preview confirmation. Passwords and login information never enter the Agent conversation.

Every 0.10.0 plan contains one role: reader, editor, or publisher. For an existing Agent, the user chooses the Space and role before generating the one-time code; exchange atomically creates or updates the Space Grant and binds an identity-only Credential to it. Only the Grant stores a role; the server derives all scopes at request time. Legacy viewer, full, permissionPreset, approvalMode, and custom-scope inputs are not accepted. Publisher eligibility does not change the Space policy and no Agent role can approve a ChangeSet or manage members.

The user actions are:

1. Approve authorization in the browser
2. Confirm the onboarding plan
3. For Editor or Publisher, confirm the first knowledge sync preview

After completion, the Agent connects to one local agentwiki MCP gateway that deterministically routes wiki_*, local_*, and knowledge_* tools.

When an Agent already exists in AgentWiki, generate the one-time unified-gateway instruction from that Agent's access page. The generated command uses the same onboard entry point with --code; it attaches the existing identity without creating a second MCP:

npx --yes @neomei/[email protected] onboard \
  --server https://agentwiki.quukk.com/api \
  --code <one-time-code> \
  --protocol ndjson \
  --agent auto

Commands

• onboard — Start the self-service onboarding flow
• onboard resume --id <sessionId> — Resume an interrupted onboarding session
• gateway --connection <id> — Run the unified gateway MCP server (stdio)
• doctor — Check installation health
• uninstall — Remove the gateway MCP and restore configuration

# Verify the installed MCP entry, local dependencies, identity, and permissions.
agentwiki-local-sync doctor

# Remove MCP connections for one client (or all clients when --agent is omitted).
# Credentials and sync-state.json are retained by default.
agentwiki-local-sync uninstall --agent codex

# Opt in to removing local credentials and/or sync state as well.
agentwiki-local-sync uninstall --agent codex --delete-credential --delete-sync-state

Removing a local connection does not revoke the server-side credential. Revoke it in AgentWiki when access must end. The shared Skill is intentionally retained: it is safe to keep and may be used by another local connection.

Data and credentials

Local source files are processed locally into a temporary knowledge envelope. knowledge_prepare produces a preview and does not upload it. Only knowledge_confirm_and_sync sends the exact confirmed envelope to the selected AgentWiki Space. Do not include secrets in a code analysis summary; the workflow requires concise structural evidence rather than source dumps.

CodeGraph code knowledge flow

Code analysis uses analysisMode: standard by default. Deep analysis is an optional Stage 2 operation and is never selected unless the user explicitly asks for deep analysis.

1. Call local_scan_sources with source paths and analysisMode: standard. It is read-only and returns the CodeGraph plan plus localScanPlanHash; it does not create or update .codegraph/.
2. Show the plan, index state, proposed .codegraph/ action, and exact hash. Obtain an explicit, current confirmation for that scan plan.
3. Call knowledge_prepare using the same source paths, analysisMode: standard, confirmedLocalScan: true, and the exact localScanPlanHash. This is the only point at which the confirmed local scanner action may occur. It generates a Preview but never uploads.
4. Show the Preview delta and previewHash, then ask separately for explicit sync confirmation.
5. Only after that second confirmation, call knowledge_confirm_and_sync with the exact jobId, previewHash, and confirmed: true.

Scan-plan consent is not sync consent. .codegraph/ is scanner-owned local index data; it is not uploaded. AgentWiki keeps its private normalized snapshots under ~/.agentwiki/workspaces/<source-key>/codegraph/current/ and generated analysis under ~/.agentwiki/workspaces/<source-key>/generated/codegraph/. These private artifacts, raw source bodies, credentials, binaries, diagnostics, and absolute paths are not uploaded.

Connection metadata is stored at ~/.agentwiki/local-sync.json; API keys are stored at ~/.agentwiki/credentials.json. Both are written owner-only (0600). Prepared preview metadata is kept at ~/.agentwiki/previews/, and source keys at ~/.agentwiki/source-keys/. Client MCP configuration contains the exact package version and connection ID, never the API key.

Supported clients

| Client | Registration behavior | Version tested | | --- | --- | --- | | Codex | Atomic ~/.codex/config.toml entry using command + args | Codex CLI 0.147.0 | | Claude Code | Atomic ~/.claude.json entry using command + args | Claude Code 2.1.211 | | OpenCode | Version-aware v1/v2 config using a command array | OpenCode 1.18.18 |

These versions were tested with isolated temporary HOME directories on 2026-08-15. The package uses an exact version in every registered gateway command.

The 0.10.0 package requires the already-published @neomei/[email protected], which contains the collaboration and Sync v3 contracts. Release verification packs the Local Sync candidate, installs it with the public protocol into an empty directory, and runs the CLI before publication.

Package contents

The npm tarball is limited to compiled dist/, the shared skill/, this README, LICENSE, and package metadata. It must not include fixtures, .env files, credentials, or absolute local paths.