Skip to content

SETUP.md

Latest commit

 

History

History
297 lines (242 loc) · 19.7 KB

SETUP.md

File metadata and controls

297 lines (242 loc) · 19.7 KB
Raw

Setup scope and project changes

ak setup always performs machine setup. It also performs project setup when the current directory contains a .git entry. ak setup --project forces that same project phase in the current directory even when .git is absent.

The flag does not select a gentler or different initializer. If project setup would already run, ak setup and ak setup --project have the same effect.

How the ak binary was obtained does not change this behavior. A local dependency or one-shot npm exec invocation still performs the same machine, current-user, and project work. See Installation and scope for the package-install methods and their separate footprints.

Warning

Project setup runs ruflo init --full --force. In an existing project, that can replace agent configuration and generated Ruflo/AQE assets. Commit or back up the project first, run from the intended project root, and preview the high-level plan with ak setup --dry-run.

Which scopes run?

Where the command is run ak setup ak setup --project
Git repository root (.git exists in the current directory) Machine + project Machine + project; the flag is redundant
New or existing non-Git directory Machine only Machine + project in that directory
Subdirectory of a Git repository without its own .git entry Machine only Machine + project in the subdirectory, not the repository root
Home directory Machine only Machine + project in the home directory; avoid this unless it is intentional

--minimal overrides both automatic detection and --project: it performs machine setup only.

Project detection does not walk upward to find a repository. For predictable results, change to the project root before running either form.

What machine setup does

The machine phase is the same with or without --project. It:

  • creates or updates the agentic-kit machine configuration;
  • ensures enabled global tools and hosts are installed, while generally retaining already-installed tool versions;
  • installs and verifies the exact Ruflo-compatible agent-browser executor, unless --no-agent-browser is selected;
  • repairs required native packages and deploys the token-audit skill;
  • reconciles agentic-kit's managed guidance blocks in the user-level Claude and Codex files that exist on the machine;
  • offers user-scope Ruflo MCP registration; and
  • when explicitly requested, installs and wires the optional deja-vu transcript companion, then builds its derived index once with deja index; and
  • applies saved host, provider, and routing choices.

ak setup is the first-time installer, not the routine upgrade command. Once the kit is installed, use ak sync to upgrade and reconverge it.

Ruflo browser executor

Ruflo's released browser MCP currently shells out to agent-browser; it has not yet shipped the Servo backend described by its accepted design ADR. Setup pins a Node-compatible 0.27.x release, verifies the package-owned native executable, and passes ~/.config/agentic-kit/agent-browser.json only to managed Ruflo MCP processes. This avoids repository config discovery and does not install the @claude-flow/browser plugin or another skill catalog.

When neither system Chrome nor a prior agent-browser payload is present, setup downloads Chrome for Testing without privileged OS dependency installation. Chrome for Testing does not publish Linux ARM64 builds. On that architecture, setup converges with the executor installed but browser readiness degraded until a compatible system Chromium/Chrome executable is supplied; sync does not retry an impossible download. Use --no-agent-browser to disable the component. Restart or reconnect Claude, Codex, and OpenCode after setup so their stdio MCP process receives the new environment.

Optional deja-vu companion

deja-vu is disabled unless setup receives --with-deja-vu. The default opted-in mode is mcp; --deja-vu-mode auto adds the host-native automatic recall surface that deja-vu 0.19.0 supports for each enabled host. The mode surfaces are not identical: Claude includes per-prompt, precompaction, action-time, and failed-command events; Codex's CLI hooks and user-owned plugin divide those events differently; OpenCode has no action-time hook.

Setup installs each exact enabled-host target with indexing and upstream guidance suppressed, then runs one deja index after all wiring. It never uses deja-vu's discover-all targets, so another agent configuration merely present on disk is not brought into Agentic Kit's ownership.

The preflight discloses that deja-vu reads coding-agent histories and creates a plaintext derived search index. Redaction is best effort, and recalled history is untrusted evidence rather than instruction. Review the complete deja-vu runbook before accepting this optional scope.

What project setup changes

Project setup first delegates to the installed Ruflo version, then applies agentic-kit's normalization and verification steps. Ruflo and agentic-qe own some generated assets, so exact generated filenames can change between their versions. The table below describes the current contract.

Path or state Existing project New/empty project
Application source, package.json, and arbitrary project files Not intentionally changed by agentic-kit. No application is scaffolded.
.claude/settings.json Regenerated by ruflo init --full --force; agentic-kit then disables claudeFlow.daemon.autoStart if it is true, and AQE may merge its hooks/settings. Custom content can be at risk. Created with Ruflo settings, then normalized and optionally extended by AQE.
.claude/settings.local.json Valid existing JSON is preserved and merged with an absolute env.CLAUDE_FLOW_DB_PATH. A one-time .bak is created before agentic-kit writes it. Invalid JSON is treated as empty. Created with the absolute memory path.
.claude/skills/, .claude/commands/, .claude/agents/, .claude/helpers/ Ruflo's matching generated assets are overwritten; AQE assets are then added or refreshed. Unrelated extra files are generally not swept. Generated and populated.
CLAUDE.md Agentic-kit captures the pre-init bytes before Ruflo runs, restores user-authored prose outside its own sentinels, and reconciles the bounded managed projection before and after AQE. An exact old unsentineled lean stub is migrated; a near-match is preserved. In an AGENTS-only repository, the created file is the one-line @AGENTS.md reference. Created only when required: bounded managed guidance, or a one-line @AGENTS.md reference when that is the existing project guidance source.
.mcp.json Ruflo force-init regenerates this file before agentic-kit removes project-local ruflo, claude-flow, ruv-swarm, and flow-nexus entries. The file is deleted if those are the only remaining content. AQE may subsequently add its own server. Because regeneration happens first, pre-existing custom MCP entries can be lost; preserve them separately and restore them after setup. Temporarily generated and sanitized; it may be absent afterward unless AQE or another retained entry needs it.
Claude's project-local ruflo MCP registration Removed with claude mcp remove ruflo -s local; agentic-kit offers user-scope registration instead. Same behavior.
.claude-flow/ generated config and runtime support files Ruflo-generated files are refreshed. Agentic-kit initializes memory and swarm state, starts the local-only daemon, and injects/heals the status-line footer. Created and initialized.
.swarm/memory.db and adjacent memory stores Initialized or migrated in place. Agentic-kit writes a disposable verification record, confirms the on-disk row, and removes only that probe. Created/initialized and verified.
.agentic-qe/ and AQE integration assets With AQE enabled, aqe init --auto migrates or refreshes its database, configuration, workers, skills, agents, hooks, and platform integrations. Generated assets can change with the installed AQE version. Created and initialized when AQE is enabled.
Oversized .agentic-qe/*.rvf stores An RVF file over 2 GiB and its .lock, .idmap.json, and .manifest.json sidecars are removed before AQE initialization. Normal-sized stores are left to AQE. Normally not applicable.
Root .gitignore Ruflo appends missing runtime/local-secret exclusions while preserving existing entries. Created or extended as needed.
.agents/skills/ Ruflo's auto-detected Codex and skills.sh projections are suppressed. Existing unreceipted skills are preserved for review; agentic-kit never infers deletion ownership from a familiar name. AQE may install its current curated Codex skills when that integration is enabled. Only the explicitly enabled host integration may populate this root.
Project AGENTS.md Arbitrary project content and upstream-owned sentinels are preserved. Agentic-kit replaces/removes only its own complete sentinel-delimited blocks and collapses duplicate owned blocks. Created only when a selected integration needs project-scoped managed guidance.

For AQE 3.14.1 and newer, Codex-enabled setup passes the persisted kit.json preference "aqeCodexGuidance": "compact" to AQE's initializer. Use "full" for AQE's full eager instructions or "none" to omit them. An explicit preference survives subsequent setup runs; older AQE versions retain their supported initializer arguments. AQE owns and updates its guidance block.

Setup with Codex enabled inventories the effective user Codex MCP configuration even in machine-only mode. When project setup is active it inventories that project's Codex MCP configuration too. An exact recursive [mcp_servers.codex] entry and the exact deprecated claude-flow Ruflo transport are listed in the setup trust manifest, backed up, removed only after the setup confirmation (or --yes), and re-probed before setup may report success. A fresh recovery copy captures the immediate pre-repair bytes; symlinked or otherwise non-regular config files remain report-only. Project files and the legacy Ruflo replacement stay outside this repair scope under --minimal or when setup is run outside a project.

Project setup also reapplies enabled host/provider wiring, seeds the default per-activity routing policy in dual-host mode, registers the workspace-aware Ruflo MCP in Codex, and retires agentic-kit-owned legacy Claude-to-Codex project entries.

Guidance precedence and repeatability

The project guidance result is defined by ownership, not by which initializer ran last:

Starting state First ak setup --project Re-run / disable behavior
No CLAUDE.md or AGENTS.md Create only the enabled integrations' bounded project guidance. A second run is byte-identical when configuration is unchanged.
User-authored CLAUDE.md Preserve user text and reconcile agentic-kit sentinels around it. Replace the owned span in place; disabling removes only that span.
User-authored AGENTS.md, no CLAUDE.md Preserve AGENTS.md; create one line, @AGENTS.md, for Claude instead of copying equivalent prose. The reference stays single and stable.
Prior agentic-kit block Replace its complete sentinel span; collapse duplicate complete copies. Re-running never stacks another equivalent block.
Exact old unsentineled lean stub Migrate that recognized prior-art shape to current managed guidance. Future runs use ordinary sentinel ownership.
Incomplete sentinel or edited near-match Preserve as foreign content and report/review the ambiguity. Never infer deletion authority from a prefix or resemblance.

Agentic-QE's BEGIN AGENTIC-QE CODEX block is owned by Agentic-QE, not by this merge engine. Setup uses a bounded compatibility guard and reconciles around AQE initialization, but does not claim arbitrary AQE content. Ruflo is called with --no-global, --no-codex-detect, and --no-skills-sh to declare the machine/Codex ownership boundary. Published Ruflo 3.38.21 does not honor the two hyphenated skill flags (ruflo #3167), so agentic-kit additionally uses scripted --format json mode and RUFLO_NO_SKILLS_SH=1; both independently suppress the optional projections in that release. Existing unreceipted skills remain review-only. A future upgrade may remove a stale projection only when its path and last-written digest are receipt-owned and the file is still unchanged. Generated settings, skills, agents and hooks remain subject to the upstream ownership and overwrite warnings in the table above.

ak x reference diff inspects every enabled host target with the same target-aware selection; ak x reference sync reconciles those targets and is byte-idempotent on the second run. On the 2026-09-02 reference machine, Claude, Codex and OpenCode machine guidance all reported canonical-managed, while the project's AGENTS.md remained untouched.

Setup trust manifest

Before making any machine, user, or project change, setup derives one manifest from the enabled host adapters and prints every applicable approval, registration, and host-integration change. Interactive setup asks for one confirmation after this preflight. --yes suppresses the question but still prints the manifest, so automation retains an auditable record; --dry-run is the non-mutating way to inspect the effective manifest for the current flags. A non-interactive setup with applicable trust changes must pass --yes; otherwise it prints the manifest and exits before mutation.

The host registry requires every present or future host adapter to declare an approval posture and its setup-time trust changes. A future host cannot pass registry validation without that declaration, and setup consumes it without a host-specific disclosure branch. Enabling a host later with ak host pick uses the same registry-derived preflight for changes that command applies; already-enabled hosts are not prompted again.

Claude Code project auto-approvals

Project setup discloses the exact Claude Code rules that Ruflo and agentic-qe may ensure or retain in .claude/settings.json:

Owner Auto-approved rule Effect
Ruflo Bash(npx @claude-flow*) Run scoped @claude-flow npx commands
Ruflo Bash(npx claude-flow*) Run scoped claude-flow npx commands
Ruflo Bash(node .claude/*) Run repository-local .claude Node helpers
Ruflo mcp__claude-flow__* Call the project Ruflo MCP tool family
agentic-qe Bash(npx agentic-qe:*) Run scoped agentic-qe npx commands
agentic-qe Bash(npx @anthropics/agentic-qe:*) Run scoped @anthropics/agentic-qe npx commands
agentic-qe mcp__agentic-qe__* Call the project agentic-qe MCP tool family

The last three rules are omitted with --no-aqe. Rules that existed before setup remain user-owned. After each upstream initializer, agentic-kit compares the resulting allow-list with the manifest: any newly added, undisclosed rule is removed and setup fails instead of silently expanding project trust.

Codex and OpenCode

Codex does not need an agentic-kit auto-approve list. The manifest names the user-scope Codex-to-Ruflo MCP registration and the AQE Codex integration that project setup will create. Agentic-kit does not alter Codex's sandbox or approval policy.

OpenAI's Claude Code plugin for Codex is an optional App Server-based interactive path. It is user-owned: setup and sync never install, enable, update, or remove it. If that exact companion is accidentally enabled as a Codex plugin, ak status and ak audit hooks report the placement error. ak heal hooks can prepare an approval-required, receipt-backed change that disables only its Codex entry.

Codex also retains exclusive ownership of third-party plugins. Agentic-kit never installs or enables a Codex plugin (including security-guidance), and setup/sync never rewrites Codex's plugin tables or cache. The explicit healer exception above never touches the plugin cache or Claude Code's plugin state. ak status reads enabled bundles to report known placement, hook, and skill portability problems.

All enabled hosts converge on the same project-scoped Ruflo memory contract. Claude receives the absolute CLAUDE_FLOW_DB_PATH in project settings. Codex's user-scoped Ruflo MCP registration launches ak x ruflo-mcp, which derives the pin from the workspace at process start. OpenCode's managed MCP gateway and lifecycle bridge receive its project directory and set the same absolute pin. Ruflo's native bridge may write .swarm/agentdb-memory.db beside the pinned .swarm/memory.db; that sibling is the active native store, not configuration drift. ak x verify memory proves the actual writer with a disposable round trip.

OpenCode's user-scope manifest names all four wildcard tool approvals, the Ruflo and optional Brain MCP registrations, the lifecycle plugin, and the managed agent/skill/guidance projection. These are workspace-trust grants, not an agentic-kit sandbox.

The separately offered Claude user-scope Ruflo MCP registration retains its own dedicated prompt because it is optional rather than a deterministic setup change. --yes accepts that prompt as documented.

Existing projects

For an existing project:

  1. Commit or back up the working tree, especially CLAUDE.md, .mcp.json, .claude/, .claude-flow/, .agentic-qe/, and .agents/.
  2. Change to the repository root. Do not rely on --project from a nested directory.
  3. Run ak setup --dry-run to confirm that both machine and project phases are intended. The preview is high-level; it is not a per-file diff.
  4. Run ak setup at a Git root, or ak setup --project only when the intended root has no .git entry.
  5. Review the resulting diff, restoring custom MCP entries or generated-file customizations where necessary, then run ak status.

If agentic-kit is already working in the project, prefer ak sync. Re-running setup is normally appropriate only when deliberately rebuilding the initial integration state.

New projects

For an empty or newly created directory:

  • If it has already been initialized with Git, the two commands are equivalent.
  • If it has no .git entry, plain ak setup performs machine setup only; ak setup --project also creates the Ruflo/AQE integration in that directory.
  • Neither form runs git init, creates application source, selects a framework, or installs project application dependencies.

Flags that alter project setup

  • --minimal skips project setup entirely, even with --project.
  • --no-aqe skips AQE installation/configuration for this setup and records AQE as disabled in agentic-kit's machine configuration.
  • --codex, --opencode, and --primary-host enable and wire the selected hosts before the project phase.
  • --with-deja-vu opts into the transcript companion. It defaults to MCP mode.
  • --deja-vu-mode mcp|auto selects on-demand tools or host-native automatic recall. It is valid only with the companion enabled.
  • --no-deja-vu records the companion as disabled and is mutually exclusive with --with-deja-vu.
  • --yes accepts prompts; it does not hide the setup trust manifest or change the project mutation contract.
  • --dry-run prints a high-level plan and changes nothing.

The clean-machine regression runs from the packed release artifact on GitHub's macos-latest runner with disposable HOME, XDG directories, npm global prefix/cache, Brain KB, and project directory. Local regression coverage uses the same isolation model in a child process. Neither test runs setup against the developer's existing home or global npm prefix.

See Upgrading for the setup versus sync lifecycle and Troubleshooting for setup and health-check failures. See Host support before enabling Claude, Codex, or OpenCode.