Documentation

EpiDev wiki

EpiDev is a VS Code extension that presents Kinetic ERP designable artifacts as a first-class tree, talks to ERP REST v2 directly from your machine, and exposes the same surface to AI agents. This page is the short version: install, configure one environment, understand the write gates, then get an agent connected.

Quick start

Six steps, about ten minutes. Everything after step 2 lives in the EpiDev Setup hub, which reports a fresh status per card and keeps validation and recovery actions next to the control they belong to.

Install the extension. Get EpiDev from the Visual Studio Marketplace, or search for EpiDev in the Extensions view.
Open a folder or workspace. Environment configuration and the agent stdio entry are workspace-scoped. With no folder open, setup and EpiDev: Connect Agent Clients cannot complete.
Run EpiDev: Open Setup. On first install VS Code opens the Set up EpiDev walkthrough automatically; run the command from the Command Palette (⇧⌘P / CtrlShiftP) any time to resume it. It is also reachable from EpiDev Account/Setup in EpiDev Settings.
Enter your access code. Paste the delivered code into the license card. Access is stored in VS Code SecretStorage and refreshed in the background; the card reports your access level, expiry, and whether the session is online, using offline grace, locked, or signed out. Access codes, receipts, and grants are never written to workspace settings.
Choose your AI providers. Pick the clients you actually use. EpiDev marks the ones that work with no extra configuration (GitHub Copilot Chat) and offers one-click MCP setup for the ones that need a config entry (Claude Code, Codex, Cline). See Use AI agents.
Add and test your first ERP environment. Enter the base URL, company, authentication method, and credentials, make the environment active, and finish with a passing connection test. Setup is complete only after the test passes. See Configure an ERP environment.

Good to know The Setup hub's Show on autoupdate checkbox defaults on while any section is incomplete and off once every section passes a fresh check. When on, the first window after an extension update reopens the hub in revalidation mode and re-checks license, provider connections, workspace, and the active environment. Revalidation is read-only, prompt-free when offline, and never treats a cached success as current proof.

Configure an ERP environment

An environment is one ERP instance plus the policy that governs it. You can configure several and switch between them; the active one shows in the status bar with a lock / edit / warning chip. Use EpiDev: Configure Environments to manage them and EpiDev: Select Environment to switch.

Fields stored in settings under `epiDev.environments`.
Field	What to enter
`name`	A unique key for this environment. It is used in `erp://` URIs, SecretStorage keys, audit entries, and agent tool parameters. No `/`.
`label`	Optional display name shown in the status chip, picker, and confirmation dialogs.
`baseUrl`	The instance root, for example `https://host/Instance`. REST paths are built from this value plus `/api/v2/…`.
`company`	Default ERP company segment for REST v2 OData and RPC calls.
`userName`	The ERP user for Basic authentication. The password is stored separately.
`authMode`	`basic-apikey` — username / password plus `x-api-key`. `oidc` — interactive SSO sign-in, access token sent as a Bearer header, with Basic + API key as the hybrid fallback when not signed in.
`mode`	`readonly` (default), `writable`, or `live`. See Safety modes.
`agentWrites`	`deny`, `confirm` (default), or `allow` — the policy applied to AI agents specifically.
`domains`	Optional per-domain overrides that narrow the environment further, e.g. AppStudio read-only inside a writable environment.

Credentials

The password and API key are never part of settings. They live in VS Code SecretStorage under epiDev/<name>/password and epiDev/<name>/apiKey, and the environment export command excludes them by construction.

Active environment

epiDev.activeEnvironment names the environment every tree read, verb, and agent call uses unless a call passes an explicit environment override. An unknown value warns and falls back to the first valid configured environment.

Connection test

EpiDev: Test Connection runs one cheap probe call and reports whether the instance answered, the identity it resolved, and the live server version — the version is always probed, never hardcoded. If the probe fails, re-check the baseUrl shape, the company, and the stored credentials before changing anything else.

SSO For Kinetic SaaS tenants, the environment manager can discover the authority and client settings from the tenant login configuration, so oidc environments usually need only the tenant id. Basic + x-api-key remains the fallback when configured.

Safety modes

Each environment declares a mode and a separate agent-write policy. The extension is the sole authority for both — no server-side configuration can loosen them. Defaults are the safe ones: readonly and confirm.

Environment `mode` — applies to humans and agents alike.
Mode	Effect
readonly	Mutating verbs and tools are hidden in the UI and omitted from the agent tool list. Mutating REST calls are refused at the gate-token boundary. Reads work normally. This is the default.
writable	The only mode in which anything is written. Humans get the full set of verbs through the confirmation and audit pipeline; agents are additionally governed by `agentWrites`.
live	The most restrictive mode, for production and other environments you do not want touched. It is read-only everywhere: mutating verbs and tools are hidden, `agentWrites` is forced to `deny`, and per-session confirmation memory is disabled.

Read this once live does not mean "writes allowed on the live system". It is a distinct, stricter control level that combines read-only access with forced agent denial. If you need to write, use a writable environment.

`agentWrites` — applies to AI agents on a `writable` environment.
Policy	Effect
`deny`	Agent writes are refused with a hint pointing at the setting. Humans are unaffected.
`confirm`	Each agent write raises the confirmation prompt, annotated with the requesting client, before anything is sent. This is the default.
`allow`	Agent writes execute without a per-call prompt, but still through the same single-use gate token and audit pipeline.

Per-domain overrides narrow further, never widen: the effective mode is the most restrictive of the environment mode and the domain override. Use EpiDev: Set Environment Mode to change the mode of the active environment.

Work with artifacts

The EpiDev view in the activity bar has one root per domain. Expansion is lazy — a node fetches only when you open it — with per-environment, per-node caching, search to narrow a list, and client-side Load more paging for large domains.

BPM
BAQ
AppStudio
Report Styles
RDD
SSRS RDL
Menus
EFx
Solutions
UD Codes

Each domain maps to its real ERP service with its own edit recipe. Coverage varies on purpose: Solutions is read-only, and UD Codes is the one domain with declared safe create and delete.

Opening an artifact

A default click on a leaf prefers a dedicated form when one exists — search criteria, report style rules, RDD structure, SysTask and SysAgent schedules, menu security tokens, UD rows, and more — each of which keeps a raw-JSON escape hatch. Otherwise the leaf opens as an erp:// document with per-domain content (.baq.json, .bpm.json, .cs, …) so VS Code picks the right language mode automatically. EFx and BPM code leaves also get cache-first C# completion, hover, signature help, and non-mutating validation.

Important erp:// documents are virtual. They are projections of server state, not files on disk, so tools that expect a filesystem path cannot read them. See Troubleshooting.

Context actions

Right-click a node for the verbs that domain declares — Run BAQ, Analyze BAQ, Copy ID, Export, Resolve launch URL, Promote EFx, create or delete a UD Code, import UD table rows, compare or sync an artifact across environments. Read verbs run immediately. Mutating verbs are hidden entirely on readonly and live environments.

Preview and run

Where a domain supports it, you can exercise an artifact without changing it: run a BAQ and inspect rows in the preview grid, analyze a BAQ definition for tables, joins, criteria, parameters and a complexity score, or validate BPM directive code against the server validator. Agents get the same dry-run path through epi_preview_update, which produces a fresh snapshot, optional validation, a build of the update, and a compact diff — and never sends the mutating request.

Saving

Every write, from the editor or from an agent, goes through the same pipeline:

Fresh snapshot. The current server state is re-fetched to use as the before-image, rather than trusting what you opened.
Conflict detection. If the server has moved since you opened the artifact, you get a conflict warning first.
Validation. The descriptor validates the payload it is about to send.
Confirmation. A modal shows a compact diff of what will change — annotated with the requesting client when the write came from an agent.
Single-use gate token. The mutating call is only reachable with a token minted for that one operation.
Refresh and audit. The tree refreshes and an entry is appended to the audit log with actor and client attribution, passed through the redaction filter.

Use AI agents

EpiDev exposes one canonical tool registry through two frontends: VS Code language-model tools, used by Copilot Chat and other VS Code-native agents, and an embedded MCP server for everything else. Both honor the same environment, mode, agent-write policy, confirmation, and audit path — connecting a second client does not create a second set of permissions.

Connecting a client

Claude Code and Codex — pick them during provider setup, or run EpiDev: Connect Agent Clients. The command detects installed runtimes, shows exactly which file it will touch and what will change, and writes the entry only after you confirm. Claude gets a workspace .mcp.json entry (with alwaysLoad, so the tools are advertised at session start); Codex gets an entry in your user ~/.codex/config.toml. Unrelated configuration is preserved, and EpiDev: Disconnect Agent Clients removes only the epidev entries.
GitHub Copilot Chat — native, with no config file to write. Keep epiDev.agent.tools.enabled on (the default) and choose agent mode in the chat view.
Any other MCP client — EpiDev: Copy MCP Config provides the same stdio snippet to paste manually.

Why the connection stays stable

Generated entries are token-free. They launch a small local stdio shim that resolves the current localhost endpoint at call time from the workspace endpoint index, falling back to VS Code global-storage mirrors. The MCP server itself binds 127.0.0.1 on an ephemeral port and rotates its bearer token on every activation and on EpiDev: Restart MCP Server — but because the token never enters client configuration, window reloads and MCP restarts do not require re-copying anything.

Recommended first calls

Have the agent orient itself before it does anything expensive. This sequence answers "am I connected, to what, with which permissions" with cheap read calls, and only then reaches the optional write step:

epi_mcp_status — confirm the backend is reachable and the workspace and tool count look right. Call this first whenever tools appear unavailable.
epi_environments — list configured environments, the active one, its effective mode, and the agent-write policy. Never returns secrets.
epi_tool_catalog — look up the exact tools and schemas for the task at hand instead of guessing names.
epi_list_artifacts — list compact rows for one domain, narrowed with search or parentId, paging via the returned offset.
epi_get_artifact — read one artifact's content, continuing with offset for large definitions.
Only then, and only when a change is actually intended: epi_preview_update to see the diff, followed by epi_apply_update, which still passes through policy, confirmation, gate token, and audit.

Reading what you are looking at To act on the artifact you currently have selected in the tree or open in an active erp:// editor, the right call is epi_get_selected_artifact. It resolves the selection and the active virtual editor directly; a chat cannot reach that content through normal file context because there is no path on disk. epi_get_open_artifacts lists open erp:// tabs without their content.

Sample prompts

Paste these into a connected client to check the surface end to end. All four are non-mutating: the first three are plain reads, and the last exercises the dry-run preview path, which stops before the mutating request.

List BPM directives on Erp.BO.Part.Update and show the code of the enabled ones.

Exercises domain listing plus reading a code leaf.

Run BAQ ZPartAudit with top 25 and summarize the first five rows.

Executes a stored BAQ with a row cap and reads results back.

Analyze BAQ ZPartAudit and explain why its complexity level is COMPLEX.

Returns structure, joins, subqueries, and definition diagnostics.

Preview the update for BAQ ZVSX-AgentScratch and show only the diff summary.

Dry run only — the mutating request is never sent.

Troubleshooting

Symptom	What to do
"Open a workspace folder…"	Environment configuration and the stdio entry are workspace-scoped. Open a folder or workspace, then re-run `EpiDev: Open Setup` or `EpiDev: Connect Agent Clients`.
No environment configured	The tree and every agent tool need one. Run `EpiDev: Open Setup` (or `EpiDev: Configure Environments`), add base URL, company, auth method and credentials, make it active, and finish with a passing connection test.
Connection test fails	Check that `baseUrl` is the instance root (`https://host/Instance`, no REST path), that the company matches, and that the password and API key are stored for this environment. For `oidc`, confirm you are signed in — otherwise the hybrid path needs valid Basic + API key values.
Claude shows no EpiDev tools right after a session starts	Client-side indexing takes roughly two to three minutes after a fresh session start. Wait and retry; do not fall back to reading files from disk. If it persists, ask the agent to call `epi_mcp_status`.
An agent cannot read an open `erp://` editor	Expected — `erp://` content is a virtual document with no disk path, so file-based tools find nothing. Use `epi_get_selected_artifact` for the current selection or active editor, or `epi_get_artifact` by id.
A write was refused	Check the environment's mode. `readonly` and `live` omit the gated-write tools from the agent tool list and refuse them at dispatch, and `live` also forces `agentWrites` to `deny`. To write, switch to a `writable` environment whose `agentWrites` is `confirm` or `allow`.
MCP returns 401 after a reload	The port and token rotate on activation. Clients on the generated stdio entry re-resolve automatically and need nothing. If you pasted the rotating HTTP form by hand, re-copy it with `EpiDev: Copy MCP Config`, or reconnect to move to the stable stdio entry.
Copilot agent mode shows no ERP tools	Enable `epiDev.agent.tools.enabled` and reload the window.

Security

Your ERP traffic is direct. Requests go from the extension on your machine to the ERP server you configured. There is no EpiDev proxy in the path.
Credentials stay in VS Code SecretStorage. Passwords and API keys are never written to settings, environment exports, logs, or audit entries. Log lines, error details, and audit records pass through a redaction filter covering authorization headers, API keys, cookies, tokens, and the environment's own secret values.
The MCP server is local only. It binds 127.0.0.1 on an ephemeral port and requires a bearer token on every request; the port and token rotate on each activation and restart. Generated client configuration is token-free.
Writes are gated and audited. Nothing mutates without the environment's mode allowing it, the agent-write policy allowing it, confirmation where required, and a single-use gate token — and every attempt is appended to an append-only audit log with actor and client attribution.

Full terms and the privacy policy are linked from the EpiDev homepage.