devilop - agent installation and project guide
Package version: 0.26.1
Website: https://devilop.tech

Read this guide in full. Install devilop on the person's computer, where their
coding agent works. The public website distributes files; it is not the map app.
Do not install or run the project-map server on the public website's host.
Reply to the person in your agent client, in their language. devilop has no chat.
Continue in this same conversation. Do not create another agent or native session
to finish setup. Keep setup and verification quiet: start servers hidden, use
isolated headless checks, and do not open windows, browser panels or screens in
the person's live map. Only open or demonstrate a screen when the person asks.

1. Reuse what is already there

First check whether the local app responds. Use a short timeout:

  macOS / Linux:
  curl --fail --silent --show-error --max-time 3 http://127.0.0.1:4317/api/health

  Windows PowerShell:
  curl.exe --fail --silent --show-error --max-time 3 http://127.0.0.1:4317/api/health

A devilop health response identifies the app and its version. If it is already
running, fetch its local guide and use its exact command and installation path:

  macOS / Linux:
  curl --fail --silent --show-error http://127.0.0.1:4317/agent

  Windows PowerShell:
  curl.exe --fail --silent --show-error http://127.0.0.1:4317/agent

If devilop_* tools are already connected, call devilop_guide and devilop_context.
Do not create a second installation or a second map for an existing project.
If an installation exists but is stopped, start that copy. Do not stop another
program to claim port 4317. Use the local guide if the person has a custom port.

The app stores maps and its registry in .devilop/ next to its program, unless an
existing configuration selects another data folder. Preserve that folder, its
backups and machine settings. Never modify data files while the server runs.
Do not read or print tokens, .env files, private keys or certificates.

2. Requirements and download

Node.js 22 or newer is required. Check: node --version
If it is missing or older, install a supported Node.js release for this computer
from the official site: https://nodejs.org/en/download
Reopen the terminal if needed and check node --version again.
There are no external runtime dependencies, no build step and no npm install.

Package for this website release:
  https://devilop.tech/download/devilop-0.26.1.tar.gz
Checksums:
  https://devilop.tech/download/SHA256SUMS

The archive contains exactly one top-level directory, devilop/. Inside are the
program, Windows and macOS launchers, src/, public/, bundled fonts and licenses,
package.json, README files, docs/reference.md and the README screenshot. It does
not contain maps, .git, client settings, .env, access keys or deployment files.
Use the versioned website package for this release. The public source repository
is https://github.com/mathew5612/mycel and can lag behind the website download.

Install outside the person's connected project folder. One app serves all local
projects. The commands below install a NEW copy and refuse an existing target.
Choose another parent directory if the default would be inside the project.

macOS / Linux (POSIX shell):

  set -eu
  work=$(mktemp -d)
  printf 'Download directory: %s\n' "$work"
  file=devilop-0.26.1.tar.gz
  curl --fail --location --silent --show-error "https://devilop.tech/download/$file" -o "$work/$file"
  curl --fail --location --silent --show-error https://devilop.tech/download/SHA256SUMS -o "$work/SHA256SUMS"
  (
    cd "$work"
    if command -v sha256sum >/dev/null 2>&1; then
      sha256sum -c SHA256SUMS
    else
      shasum -a 256 -c SHA256SUMS
    fi
  )
  install_parent="$HOME/.local/share"
  if [ -e "$install_parent/devilop" ] || [ -L "$install_parent/devilop" ]; then
    echo "Existing devilop found: reuse it; do not overwrite its maps."
    exit 1
  fi
  mkdir -p "$install_parent"
  tar -xzf "$work/$file" -C "$install_parent"
  chmod +x "$install_parent/devilop/devilop.command"
  node "$install_parent/devilop/devilop.mjs" start

The app is now in ~/.local/share/devilop. Keep the printed download directory
until verification is complete. A checksum failure must stop installation.

Windows PowerShell (Windows 10/11 with tar.exe):

  $ErrorActionPreference = 'Stop'
  $work = Join-Path ([IO.Path]::GetTempPath()) ('devilop-download-' + [guid]::NewGuid())
  New-Item -ItemType Directory -Path $work | Out-Null
  Write-Host ('Download directory: ' + $work)
  $file = 'devilop-0.26.1.tar.gz'
  $archive = Join-Path $work $file
  $checksums = Join-Path $work 'SHA256SUMS'
  Invoke-WebRequest -Uri ("https://devilop.tech/download/" + $file) -OutFile $archive
  Invoke-WebRequest -Uri 'https://devilop.tech/download/SHA256SUMS' -OutFile $checksums
  $line = @(Get-Content -LiteralPath $checksums | Where-Object { $_ -match ('^[a-fA-F0-9]{64}  ' + [regex]::Escape($file) + '$') })
  if ($line.Count -ne 1) { throw 'Missing or ambiguous devilop checksum.' }
  $expected = ($line[0] -split '  ', 2)[0]
  $actual = (Get-FileHash -Algorithm SHA256 -LiteralPath $archive).Hash
  if ($actual -ine $expected) { throw 'Checksum mismatch. Do not extract or run this download.' }
  $installParent = $env:LOCALAPPDATA
  if (-not $installParent) { throw 'Choose a local installation parent outside your project.' }
  $app = Join-Path $installParent 'devilop'
  if (Test-Path -LiteralPath $app) { throw 'Existing devilop found: reuse it; do not overwrite its maps.' }
  tar.exe -xzf $archive -C $installParent
  if ($LASTEXITCODE -ne 0) { throw 'Archive extraction failed.' }
  node (Join-Path $app 'devilop.mjs') start
  if ($LASTEXITCODE -ne 0) { throw 'devilop did not start.' }

The app is now in %LOCALAPPDATA%\devilop. Keep the printed download directory
until verification is complete. A checksum failure must stop installation.

For an explicitly requested update, use the existing installation path and data
configuration. Download and verify first. Stop the old server with its own CLI,
make a local backup of its data folder, and replace only the runtime files listed
in the verified archive. Its devilop/ prefix must match the destination directory:
extracting into a parent is correct only if the installed directory is named
devilop. Otherwise extract into a separate staging folder and copy those runtime
files into the existing app directory. Never replace or delete .devilop/ or any
configured data folder. Do not copy maps to the website or source repository.
Start the updated app and verify the existing projects are still present.

3. Start locally and read the computer's guide

The start command runs the app in the background without opening a browser.
That is enough to continue setup through the CLI in the current conversation.
If the person explicitly asks you to open the app, use:

  macOS / Linux:
  node "$HOME/.local/share/devilop/devilop.mjs" open

  Windows PowerShell:
  node (Join-Path $env:LOCALAPPDATA 'devilop\devilop.mjs') open

The person can also double-click devilop.cmd on Windows or devilop.command on
macOS. Direct node server.mjs works in the app folder and runs in the foreground.
The default address is http://127.0.0.1:4317 and the server binds to loopback.
Do not bind to 0.0.0.0, open public firewall ports or put this app behind a public
proxy. Public web hosting is only for the landing page, guide and download.

Fetch http://127.0.0.1:4317/agent now and read it in full. This LOCAL guide is
different from https://devilop.tech/agent: it supplies the exact command for this
computer, current tool behavior and paths. Offline, the same guide is available
with node <app-directory>/devilop.mjs guide. Full offline reference:
<app-directory>/docs/reference.md. Quote paths containing spaces.

4. Connect the person's project and agent

Change the working directory to the root of the PERSON'S PROJECT, while keeping
the app outside it. Use the full app command from the local guide. For example:

  macOS / Linux:
  cd "/path/to/the/project"
  node "$HOME/.local/share/devilop/devilop.mjs" init
  node "$HOME/.local/share/devilop/devilop.mjs" context --brief --actor codex
  node "$HOME/.local/share/devilop/devilop.mjs" setup --install --hooks

  Windows PowerShell:
  Set-Location -LiteralPath 'C:\path\to\the\project'
  $cli = Join-Path $env:LOCALAPPDATA 'devilop\devilop.mjs'
  node $cli init
  node $cli context --brief --actor codex
  node $cli setup --install --hooks

init reuses the same folder's project and map. It does not copy project source
into the app. A deleted project must stay deleted unless the person asks to
reconnect it. Do not use --new or rename a project without that request.

Codex setup merges only devilop's MCP tables into this project's
.codex/config.toml and adds optional hooks in .codex/hooks.json, preserving other
settings and hooks. These are machine-specific files: do not publish them.
Future trusted Codex sessions can load the configured devilop_* tools.
If the client requests hook trust, the person handles its normal trust UI.
Continue in the requesting chat with the CLI immediately. Do not require a new
session, client restart, separate managed agent or scheduled chat automation to
finish onboarding. Tool configuration alone does not establish incoming turns.

For another client, replace the Codex setup command with:

  node <app-directory>/devilop.mjs setup --list
  node <app-directory>/devilop.mjs setup --agent <client-name>

Read the generated entry and its destination. Merge only the devilop entry into
that client's existing configuration; preserve its other servers and settings.
Explain when that client will load the entry; use the CLI in the current chat
meanwhile. Do not restart the person's client or launch a new session yourself.
Use --actor <client-name> with the CLI so activity is attributed correctly.
MCP clients provide their name.

For 0.26+ installations, connect this conversation with devilop_connect or the
local CLI's current connect --client codex|claude|cursor. Use one actual client
name, not the literal list. Read current status / devilop_current_status and the
returned delivery mode. The runtime supplies identity; never guess a chat id
or copy another connection's credentials.

  Codex: in this chat's native shell, run the exact local CLI with
  current connect --client codex. A supported native queue uses that runtime's
  current chat id. Its acceptance means queued, not received or completed; an
  unloaded or paused chat may keep the message queued. MCP can lack the native
  id even when this chat's shell has it. For a native queue notice, consistently
  use its supplied CLI receive/report/complete commands in this same chat, with
  the supplied project scope. Do not switch to an unverified MCP connection.

  Claude Code: a compatible running CLI session must explicitly enable the
  devilop channel through its native consent flow. Follow setup --agent claude
  and the current local guide. A configured environment flag or MCP entry does
  not prove that Claude accepted channel delivery. Preserve native permissions
  and report an unavailable or unverified channel honestly.

  Cursor: receive through devilop_receive while its bounded call is pending.
  Closing or timing out that call means not listening. An arbitrary idle Cursor
  chat has no confirmed external push path; do not promise idle wakeup.

Check the installed client and this connection. Protocol tests for another
computer are not evidence that this person's native client received a message.
Use a harmless delivery check only if authorized; do not edit the person's map
or launch a source assignment just to manufacture a connected status.

Without MCP, run the full CLI command from the project root. Tool definitions
are available with tools --format openai or tools --format mcp; call invokes a
tool with JSON arguments. A local model can use chat --model <model-name> against
its local model endpoint. That optional agent reads project files and maintains
maps; it does not edit the project's code. No model provider key is needed to
run devilop itself.

5. Build a map from evidence

Read context before changing an existing map, and changes at the start of every
step. Check selection when the person refers to a selected block. Reuse what is
already mapped; do not rebuild it blindly. For an empty map, read the file tree,
README, manifests and entry points, then build the map as you understand it so
the person sees it grow. Describe observed behavior and flag uncertain parts.
Never mark planned work as implemented or checked without evidence.

Use the person's language for titles, text, notes, link labels, proposal titles,
history reasons and activity. Use English only if their language is unknown.
Keep existing code identifiers unchanged where they are needed in metadata.
The app's English/Russian interface setting does not choose the map's language.

Four levels follow nesting:

  Concept: what a part is and why someone needs it. A short plain title and one
  sentence; readable without programming knowledge.

  Mechanics: how that part behaves, in clear steps. Describe what a person does,
  what information moves and what result appears. Keep code names and jargon out
  of Concept and Mechanics, including their notes and link labels.

  Technical: components, files, libraries, data, configuration and technical
  constraints. Keep source paths and implementation names here or in the block's
  files/test metadata.

  Code: precise descriptive text of how a method executes, in execution order.
  Explain inputs, conditions, branches, state changes, outputs and failures in
  prose. Use an action as the title. For example: "Reject an empty order" with
  "Read the submitted items. If none remain, return a validation error before
  reserving stock." Do not use function-call syntax, source snippets, method
  signatures or file paths as the deepest-level title or description. Files stay
  on Technical or in metadata; do not substitute a function name for an account
  of what the method actually does.

Keep top-level text short. Give each mechanics block a technical sub-map; add
Code steps where execution has meaningful detail. Connect blocks on the same
level. Automatic layout handles positions and sizes. Build in small coherent
parts rather than submitting an unreadable whole-project dump.

Use devilop_build for an initial or authorized structure; CLI build reads a
UTF-8 JSON file and can be repeated after interruption without duplicating the
same blocks. Use devilop_apply for authorized point edits. Follow the local
guide for schemas and level checks. Never disable level checks unless the
person explicitly requested the exceptional wording.

6. Keep the map current while working

Use doing to show the current activity and involved blocks, then doing --done
when finished. Update only changed fields and respect human deletions. Stages
and their task UI are withdrawn pending redesign: preserve legacy data, but do
not create a stage plan or require stage-based work. A native client plan reports
activity only; it is not a verified implementation result.

Unapproved logic changes go through propose. The person edits the proposal and
chooses Accept or Reject in devilop; do not decide on their behalf. Actions they
already authorized do not need another approval. Proposal decisions are immediate.

Human map edits and visual drafts are held until Finish edits. Block requirements
are the person's exact wishes, separate from the current behavior: preserve their
wording and omitted values, and never erase or mark them complete automatically.
Bind user-visible blocks to real local pages, regions and prepared states through
view; named states need an application handler. Follow the installed local guide
for preparing and checking these screens, not an invented image of the app.

Read the immutable submitted assignment through current receive or devilop_receive,
including its scope, changes and assigned draft hashes. Preserve executionId,
batchId and payloadHash for the result. The live map can already contain newer
unfinished edits. Reading context, changes or a package is not completion.
All clients share the same HTTP/CLI/MCP contract, with separate identities and
one source-writing lease per project. The private broker owns credentials and
completion; never put keys in prompts, model results or native notifications.

Supported native queues and channels notify each new Finish edits submission
even while an older package is queued, paused or running. Active-receive clients
need a pending call; when it ends, unprocessed packages stay saved. A notification
does not bypass the execution order. If receive returns busy, confirm receipt in
this chat, identify blockedBy and explain what must finish or be resolved first.
Do not silently drop the new request, cancel older work or apply a later package
out of order.
The avatar distinguishes actual listening, queue acceptance, agent receipt and
work. A recent contact or background notification is not proof of source work.

A separately managed native session is optional only when the person explicitly
chooses that mode. Follow the installed local guide for run and supported client
adapters. That runner owns its native session and lifecycle; its model returns
the requested result envelope instead of also claiming or completing the package.
Never present that separate session as connecting the person's existing chat.

Apply only the approved package to real source, translating visual placement into
appropriate responsive layout. Run checks and verify actual prepared screens in
an isolated hidden environment, without navigating the person's live workspace.
Use current report|complete or devilop_result with the exact assignment and real
checks; return scoped descriptions and check marks through result.blocks.
Completion requires every assigned draft's exact version; the server removes
only unchanged applied drafts on the same view and node incarnation.
Preserve newer edits and requirements. Do not clear all current drafts or manually
clean them before completion. Lost leases and uncertain partial changes
require reconciliation before another writer starts. Native permission requests
need a real human answer: never approve them on the person's behalf.

For long owned checks, follow the local guide for current exec / devilop_current_exec;
it keeps liveness only while that local command actually runs, under native
permissions. The hub does not run commands. Stop on lost ownership. An opaque MCP
connection cannot be safely matched to a native hook by guessing: cancellation
of its owned operation or explicit disconnect fences it immediately; otherwise
missing liveness requires reconciliation within the broker's bounded timeout.

On older installations, follow their local guide and use changes or a bounded wait
(for example wait --timeout 30) for notifications. A wait returns only to a running
caller; it cannot guarantee a fresh model turn. Do not silently install an update
or launch an endless wait after completing the person's request. Legacy 0.24
does not contain the current-chat module; do not promise newer behavior for it.

Mutations use expectedRevision. MCP tools and the CLI handle the normal revision
flow. On a conflict, reread current context/changes and merge your intended edits;
never resend an old full map with only a newer revision number.

Keep block files metadata accurate. Use hooks, watch or touch to track changed
files. For direct map maintenance, update affected descriptions, then fresh only
when the description really matches the code; mark only checks actually run.
For submitted work, return descriptions and marks through result.blocks so an
older result cannot mark newer human wishes as passed. The agent runs checks in
the correct project folder; the app server does not execute arbitrary check
commands. Report checks actually run,
unresolved failures and skipped coverage. Secret scans report locations only,
never secret contents.

7. Completion and optional virtual machines

Verify health and project context through the API/CLI. Any browser verification
uses an isolated headless fixture, not the person's live map. Confirm the current
chat's actual delivery mode and limits, or explain that MCP tools will load later
while the CLI already works here. Tell the person the app location, optional
browser address, what map work was done and what is still unverified.
Clear activity before ending. Leave the requested local app running; do not
silently discard maps, launch another agent or create a public map endpoint.

Virtual-machine access is optional and separate from a normal local install.
Follow the LOCAL /agent guide. Only the person approves an access request in
the host app. Machines receive separate revocable keys; do not copy, print or
send the host token. A VM's project paths belong to that VM, and the host must
not inspect them. Do not enable remote access unless it is part of the person's
request.