v3/implementation/init/API.md
Programmatic API for the V3 init system.
import {
executeInit,
detectPlatform,
DEFAULT_INIT_OPTIONS,
MINIMAL_INIT_OPTIONS,
FULL_INIT_OPTIONS,
type InitOptions,
type InitResult,
type PlatformInfo,
} from '@claude-flow/cli/init';
Main initialization function.
async function executeInit(options: InitOptions): Promise<InitResult>
Parameters:
options: InitOptions - Configuration optionsReturns:
Promise<InitResult> - Result with created files and errorsExample:
import { executeInit, DEFAULT_INIT_OPTIONS } from '@claude-flow/cli/init';
const result = await executeInit({
...DEFAULT_INIT_OPTIONS,
targetDir: '/path/to/project',
sourceBaseDir: '/path/to/claude-flow',
force: true,
});
if (result.success) {
console.log(`Created ${result.created.files.length} files`);
console.log(`Platform: ${result.platform.os}`);
}
Detect current operating system and environment.
function detectPlatform(): PlatformInfo
Returns:
PlatformInfo - Platform detection resultsExample:
import { detectPlatform } from '@claude-flow/cli/init';
const platform = detectPlatform();
console.log(`OS: ${platform.os}`);
console.log(`Shell: ${platform.shell}`);
console.log(`Config dir: ${platform.configDir}`);
interface InitOptions {
targetDir: string;
sourceBaseDir?: string;
force: boolean;
interactive: boolean;
components: InitComponents;
hooks: HooksConfig;
skills: SkillsConfig;
commands: CommandsConfig;
agents: AgentsConfig;
statusline: StatuslineConfig;
mcp: MCPConfig;
runtime: RuntimeConfig;
}
interface InitResult {
success: boolean;
platform: PlatformInfo;
created: {
directories: string[];
files: string[];
};
skipped: string[];
errors: string[];
summary: {
skillsCount: number;
commandsCount: number;
agentsCount: number;
hooksEnabled: number;
};
}
interface PlatformInfo {
os: 'windows' | 'darwin' | 'linux';
arch: 'x64' | 'arm64' | 'arm' | 'ia32';
nodeVersion: string;
shell: 'powershell' | 'cmd' | 'bash' | 'zsh' | 'sh';
homeDir: string;
configDir: string;
}
interface InitComponents {
settings: boolean;
skills: boolean;
commands: boolean;
agents: boolean;
helpers: boolean;
statusline: boolean;
mcp: boolean;
runtime: boolean;
}
import { generateSettings, generateSettingsJson } from '@claude-flow/cli/init';
// Generate settings object
const settings = generateSettings(options);
// Generate JSON string
const json = generateSettingsJson(options);
import { generateMCPConfig, generateMCPJson, generateMCPCommands } from '@claude-flow/cli/init';
// Generate MCP config object
const config = generateMCPConfig(options);
// Generate .mcp.json content
const json = generateMCPJson(options);
// Generate manual add commands
const commands = generateMCPCommands(options);
// ['claude mcp add claude-flow -- npx @claude-flow/cli mcp start', ...]
import {
generatePreCommitHook,
generatePostCommitHook,
generateSessionManager,
generateAgentRouter,
generateMemoryHelper,
generateWindowsDaemonManager,
generateWindowsBatchWrapper,
generateCrossPlatformSessionManager,
generateHelpers,
} from '@claude-flow/cli/init';
// Generate individual scripts
const preCommit = generatePreCommitHook();
const sessionMgr = generateCrossPlatformSessionManager();
const windowsDaemon = generateWindowsDaemonManager();
// Generate all helpers based on options
const helpers = generateHelpers(options);
// { 'pre-commit': '...', 'session.js': '...', ... }
import { generateStatuslineScript, generateStatuslineHook } from '@claude-flow/cli/init';
// Generate statusline.js content
const script = generateStatuslineScript(options);
// Generate shell hook content
const hook = generateStatuslineHook(options);
Recommended settings for most projects:
Lightweight configuration:
Everything enabled:
import { executeInit, DEFAULT_INIT_OPTIONS } from '@claude-flow/cli/init';
const result = await executeInit({
...DEFAULT_INIT_OPTIONS,
targetDir: process.cwd(),
});
import { executeInit, DEFAULT_INIT_OPTIONS } from '@claude-flow/cli/init';
const result = await executeInit({
...DEFAULT_INIT_OPTIONS,
targetDir: '/my/project',
sourceBaseDir: '/path/to/claude-flow', // Source for skills/commands/agents
force: true,
components: {
...DEFAULT_INIT_OPTIONS.components,
statusline: true,
},
skills: {
core: true,
agentdb: true,
github: false, // Skip GitHub skills
flowNexus: false,
v3: true,
all: false,
},
runtime: {
topology: 'adaptive',
maxAgents: 20,
memoryBackend: 'agentdb',
enableHNSW: true,
enableNeural: true,
},
});
import { executeInit, detectPlatform, DEFAULT_INIT_OPTIONS } from '@claude-flow/cli/init';
const platform = detectPlatform();
const result = await executeInit({
...DEFAULT_INIT_OPTIONS,
targetDir: process.cwd(),
// Platform-specific adjustments
components: {
...DEFAULT_INIT_OPTIONS.components,
// Enable statusline on Unix-like systems
statusline: platform.os !== 'windows',
},
});
console.log(`Initialized for ${platform.os} (${platform.shell})`);
import { executeInit, MINIMAL_INIT_OPTIONS } from '@claude-flow/cli/init';
// Install only skills
const skillsOnly = await executeInit({
...MINIMAL_INIT_OPTIONS,
targetDir: process.cwd(),
components: {
settings: false,
skills: true,
commands: false,
agents: false,
helpers: false,
statusline: false,
mcp: false,
runtime: false,
},
skills: {
core: true,
agentdb: true,
github: true,
flowNexus: false,
v3: true,
all: false,
},
});
import { executeInit, DEFAULT_INIT_OPTIONS } from '@claude-flow/cli/init';
try {
const result = await executeInit({
...DEFAULT_INIT_OPTIONS,
targetDir: '/path/to/project',
});
if (!result.success) {
console.error('Initialization failed:');
for (const error of result.errors) {
console.error(` - ${error}`);
}
process.exit(1);
}
// Log skipped files
if (result.skipped.length > 0) {
console.log('Skipped (already exist):');
for (const file of result.skipped) {
console.log(` - ${file}`);
}
}
console.log(`Success! Created ${result.created.files.length} files`);
} catch (error) {
console.error('Unexpected error:', error);
process.exit(1);
}