Function: createClientDefinition()

Makaio Framework

---

Makaio Framework / contracts / createClientDefinition

Function: createClientDefinition()

createClientDefinition(definition): object

Defined in: ../../../packages/contracts/src/client/create-definition.ts:43

Create an immutable client definition from a static object literal.

Parameters

definition

Client definition to return

binaryName?

string = ...

Binary name used for CLI detection (e.g. 'claude' for the claude binary on PATH).

configIsolation?

{ defaultPath: string; envVar: string; pathKind?: "file" | "directory"; } = ...

Config isolation descriptor for this client.

Describes the environment variable and default path used by the client binary for its config location. Optional for all clients — both managed and global binaries benefit from this descriptor:

• For managed binaries, the wiring system sets envVar to an isolated directory or file path so the binary does not share config with the user’s global install.
• For global binaries, defaultPath tells the wiring system where to write hooks when no isolation is active.

configIsolation.defaultPath

string = ...

Default config path used by the client when the env var is not set. Used by resolveBinary to determine the config location for global binaries and by wiring systems to know where to write native config when no isolation is active (e.g. '~/.claude', '~/.codex').

Must be an absolute path or start with ~/ (or equal ~ for a bare home directory reference). Whitespace-only strings and relative paths are rejected at parse time.

configIsolation.envVar

string = ...

Environment variable that overrides the client’s config location. Set by Makaio when launching a managed binary to isolate its config from the user’s global install (e.g. 'CLAUDE_CONFIG_DIR', 'CODEX_HOME').

configIsolation.pathKind?

"file" | "directory" = ...

Shape expected by envVar.

Directory targets receive the isolated config directory itself. File targets receive a file path inside the isolated config directory using the basename of defaultPath.

defaultApprovalPolicy

"always-ask" | "reject" | "full-access" = ApprovalPolicySchema

Recommended default approval policy applied when creating a harness for this client.

defaultProviderId?

string = ...

Provider definition ID to use for client-managed auth (sentinel ProviderConfig). References a ProviderDefinition.id.

description?

string = ...

Short human-readable description for UI surfaces.

id

string = ...

Stable string ID — must match the client package name suffix (e.g. 'claude-code' for @makaio/client-claude-code).

logSources?

object[] = ...

Log source definitions used by the log-import service.

managedInstall?

{ config: { archiveFormat?: "raw" | "tar.gz" | "zip"; baseUrl: string; binaryPath: string; manifestChecksumField: string; manifestPath: string; versionIndex: { latest: string; }; }; type: "manifest-bucket"; } | { package: string; type: "npm"; } | { archiveFormat: "tar.gz" | "zip"; assetPattern: Record<string, string>; repo: string; type: "github-release"; } = ...

Declarative install descriptor used by the binary manager when runtimeCapabilities.supportsManagedBinary is true.

Exactly one of the three v1 strategy variants must be provided. Omit this field for clients that are not managed by Makaio.

minimumVersion?

string = ...

Minimum supported binary version (semver, e.g. '1.0.0').

name

string = ...

Display name shown in the UI (e.g. 'Claude Code').

nativeTools?

object[] = ...

Native tools the binary exposes to the harness.

postInstall?

{ kind: string; payload?: Record<string, unknown>; } = ...

Optional post-install action to run after the binary is written to disk but before it is activated.

Omit when no post-install step is required.

postInstall.kind

string = ...

Stable identifier for the post-install handler (e.g. 'set-permissions', 'run-script').

postInstall.payload?

Record<string, unknown> = ...

Arbitrary handler-specific payload.

runtimeCapabilities?

{ hookEvents?: object[]; supportsHooks?: boolean; supportsManagedBinary?: boolean; supportsStatusline?: boolean; supportsSupervisorLaunch?: boolean; } = ...

Declarative runtime capability flags for this client.

Omitting this field or passing {} applies false to every flag. Individual flags can be opted into independently.

runtimeCapabilities.hookEvents?

object[] = ...

Declared hook events when supportsHooks is true. Lists which native event names the binary fires so the wiring layer knows what hooks to install. Must be empty when supportsHooks is false.

runtimeCapabilities.supportsHooks?

boolean = ...

The client binary supports native hook callbacks (e.g. PostToolUse, Stop) that Makaio can use to observe session lifecycle events.

runtimeCapabilities.supportsManagedBinary?

boolean = ...

Makaio manages the client binary installation and updates (e.g. via a bundled binary or a managed package install step).

runtimeCapabilities.supportsStatusline?

boolean = ...

The client binary exposes a statusline or process-watcher interface that Makaio can poll or subscribe to for runtime state.

runtimeCapabilities.supportsSupervisorLaunch?

boolean = ...

Makaio can launch this client binary as a supervised child process, enabling direct PID tracking and stdin/stdout piping.

versionCommand?

string[] = ...

Command and arguments used to query the installed binary version.

Each element is a separate argument so no shell quoting is required. The first element is resolved relative to the managed install directory (i.e. the versioned directory written by the install strategy after postInstall runs), not looked up on PATH. Subsequent elements are passed as-is (e.g. ['bin/claude', '--version'] resolves to <installDir>/bin/claude --version).

Required whenever managedInstall is provided.

Returns

Validated, normalized, frozen client definition

binaryName?

optional binaryName?: string

Binary name used for CLI detection (e.g. 'claude' for the claude binary on PATH).

configIsolation?

optional configIsolation?: object

Config isolation descriptor for this client.

Describes the environment variable and default path used by the client binary for its config location. Optional for all clients — both managed and global binaries benefit from this descriptor:

• For managed binaries, the wiring system sets envVar to an isolated directory or file path so the binary does not share config with the user’s global install.
• For global binaries, defaultPath tells the wiring system where to write hooks when no isolation is active.

configIsolation.defaultPath

defaultPath: string

Default config path used by the client when the env var is not set. Used by resolveBinary to determine the config location for global binaries and by wiring systems to know where to write native config when no isolation is active (e.g. '~/.claude', '~/.codex').

Must be an absolute path or start with ~/ (or equal ~ for a bare home directory reference). Whitespace-only strings and relative paths are rejected at parse time.

configIsolation.envVar

envVar: string

Environment variable that overrides the client’s config location. Set by Makaio when launching a managed binary to isolate its config from the user’s global install (e.g. 'CLAUDE_CONFIG_DIR', 'CODEX_HOME').

configIsolation.pathKind

pathKind: "file" | "directory"

Shape expected by envVar.

Directory targets receive the isolated config directory itself. File targets receive a file path inside the isolated config directory using the basename of defaultPath.

defaultApprovalPolicy

defaultApprovalPolicy: "always-ask" | "reject" | "full-access" = ApprovalPolicySchema

Recommended default approval policy applied when creating a harness for this client.

defaultProviderId?

optional defaultProviderId?: string

Provider definition ID to use for client-managed auth (sentinel ProviderConfig). References a ProviderDefinition.id.

description?

optional description?: string

Short human-readable description for UI surfaces.

id

id: string

Stable string ID — must match the client package name suffix (e.g. 'claude-code' for @makaio/client-claude-code).

logSources?

optional logSources?: object[]

Log source definitions used by the log-import service.

managedInstall?

optional managedInstall?: { config: { archiveFormat?: "raw" | "tar.gz" | "zip"; baseUrl: string; binaryPath: string; manifestChecksumField: string; manifestPath: string; versionIndex: { latest: string; }; }; type: "manifest-bucket"; } | { package: string; type: "npm"; } | { archiveFormat: "tar.gz" | "zip"; assetPattern: Record<string, string>; repo: string; type: "github-release"; }

Declarative install descriptor used by the binary manager when runtimeCapabilities.supportsManagedBinary is true.

Exactly one of the three v1 strategy variants must be provided. Omit this field for clients that are not managed by Makaio.

Union Members

Type Literal

{ config: { archiveFormat?: "raw" | "tar.gz" | "zip"; baseUrl: string; binaryPath: string; manifestChecksumField: string; manifestPath: string; versionIndex: { latest: string; }; }; type: "manifest-bucket"; }

---

Type Literal

{ package: string; type: "npm"; }

package

package: string

npm package name to install (e.g. '@anthropic-ai/claude-code'). May include an @version suffix to pin a specific version.

type

type: "npm"

---

Type Literal

{ archiveFormat: "tar.gz" | "zip"; assetPattern: Record<string, string>; repo: string; type: "github-release"; }

archiveFormat

archiveFormat: "tar.gz" | "zip"

Archive format of the matched release asset.

assetPattern

assetPattern: Record<string, string>

Mapping from a platform key to a glob or substring pattern used to select the correct release asset.

Keys should follow the <os>-<arch> convention used by Node.js process.platform and process.arch (e.g. { 'darwin-arm64': 'claude-darwin-arm64.tar.gz' }). Both keys and values must be non-empty strings.

repo

repo: string

GitHub repository in owner/repo format (e.g. 'anthropics/claude-code').

type

type: "github-release"

minimumVersion?

optional minimumVersion?: string

Minimum supported binary version (semver, e.g. '1.0.0').

name

name: string

Display name shown in the UI (e.g. 'Claude Code').

nativeTools

nativeTools: object[]

Native tools the binary exposes to the harness.

postInstall?

optional postInstall?: object

Optional post-install action to run after the binary is written to disk but before it is activated.

Omit when no post-install step is required.

postInstall.kind

kind: string

Stable identifier for the post-install handler (e.g. 'set-permissions', 'run-script').

postInstall.payload?

optional payload?: Record<string, unknown>

Arbitrary handler-specific payload.

runtimeCapabilities

runtimeCapabilities: object

Declarative runtime capability flags for this client.

Omitting this field or passing {} applies false to every flag. Individual flags can be opted into independently.

runtimeCapabilities.hookEvents

hookEvents: object[]

Declared hook events when supportsHooks is true. Lists which native event names the binary fires so the wiring layer knows what hooks to install. Must be empty when supportsHooks is false.

runtimeCapabilities.supportsHooks

supportsHooks: boolean

The client binary supports native hook callbacks (e.g. PostToolUse, Stop) that Makaio can use to observe session lifecycle events.

runtimeCapabilities.supportsManagedBinary

supportsManagedBinary: boolean

Makaio manages the client binary installation and updates (e.g. via a bundled binary or a managed package install step).

runtimeCapabilities.supportsStatusline

supportsStatusline: boolean

The client binary exposes a statusline or process-watcher interface that Makaio can poll or subscribe to for runtime state.

runtimeCapabilities.supportsSupervisorLaunch

supportsSupervisorLaunch: boolean

Makaio can launch this client binary as a supervised child process, enabling direct PID tracking and stdin/stdout piping.

versionCommand?

optional versionCommand?: string[]

Command and arguments used to query the installed binary version.

Each element is a separate argument so no shell quoting is required. The first element is resolved relative to the managed install directory (i.e. the versioned directory written by the install strategy after postInstall runs), not looked up on PATH. Subsequent elements are passed as-is (e.g. ['bin/claude', '--version'] resolves to <installDir>/bin/claude --version).

Required whenever managedInstall is provided.