@bastani/atomic 0.5.0-1

package/assets/settings.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Atomic Settings",
+  "description": "Configuration file for the Atomic CLI (@bastani/atomic). Stored at ~/.atomic/settings.json (global) or .atomic/settings.json (project-local).",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema URL for editor intellisense."
+    },
+    "version": {
+      "type": "number",
+      "description": "Config schema version."
+    },
+    "scm": {
+      "type": "string",
+      "enum": ["github", "sapling"],
+      "description": "Selected source control management system."
+    },
+    "lastUpdated": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of the last configuration update."
+    },
+    "prerelease": {
+      "type": "boolean",
+      "description": "When true, 'atomic update' fetches the latest prerelease instead of the latest stable release. Set automatically by the installer when using the --prerelease flag.",
+      "default": false
+    },
+    "trustedPaths": {
+      "type": "array",
+      "description": "Globally trusted workspaces that have completed provider onboarding through 'atomic init'.",
+      "items": {
+        "type": "object",
+        "required": ["workspacePath", "provider"],
+        "properties": {
+          "workspacePath": {
+            "type": "string",
+            "description": "Absolute path to the initialized workspace."
+          },
+          "provider": {
+            "type": "string",
+            "enum": ["claude", "opencode", "copilot"],
+            "description": "Provider initialized for the trusted workspace."
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@bastani/atomic",
+  "version": "0.5.0-1",
+  "description": "Configuration management CLI and SDK for coding agents",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flora131/atomic.git"
+  },
+  "keywords": [
+    "cli",
+    "sdk",
+    "coding-agents",
+    "agents",
+    "ai-engineering",
+    "harness-engineering",
+    "claude-code",
+    "copilot-cli",
+    "opencode"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "atomic": "src/cli.ts"
+  },
+  "exports": {
+    ".": "./src/sdk/index.ts",
+    "./workflows": "./src/sdk/workflows.ts"
+  },
+  "files": [
+    "src",
+    "assets/settings.schema.json"
+  ],
+  "scripts": {
+    "dev": "bun run src/cli.ts",
+    "build": "bun run build.ts",
+    "test": "bun test ./src ./tests",
+    "test:coverage": "bun test --coverage ./src ./tests",
+    "typecheck": "bunx tsc --noEmit",
+    "lint": "oxlint --config=oxlint.json src",
+    "lint:fix": "oxlint --config=oxlint.json --fix src",
+    "prepare": "lefthook install || true"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.11",
+    "@types/react": "^19.2.14",
+    "lefthook": "^2.1.4",
+    "oxlint": "^1.59.0",
+    "typescript": "^6.0.2",
+    "typescript-language-server": "^5.1.3"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.92",
+    "@clack/prompts": "^1.2.0",
+    "@commander-js/extra-typings": "^14.0.0",
+    "@github/copilot-sdk": "^0.2.1",
+    "@opencode-ai/sdk": "^1.3.17",
+    "@opentui/core": "^0.1.97",
+    "@opentui/react": "^0.1.97",
+    "commander": "^14.0.3",
+    "ignore": "^7.0.5",
+    "react": "19",
+    "yaml": "^2.8.3",
+    "zod": "^4.3.6"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,197 @@
+#!/usr/bin/env bun
+/**
+ * Atomic CLI - Configuration management for coding agents
+ *
+ * Built with Commander.js for robust argument parsing and type-safe options.
+ *
+ * Usage:
+ *   atomic                          Interactive setup (same as 'atomic init')
+ *   atomic init                     Interactive setup with agent selection
+ *   atomic init -a <agent>          Setup specific agent (skip selection)
+ *   atomic init -s <scm>             Setup specific SCM (github, sapling)
+ *   atomic chat -a <agent>          Start interactive chat with an agent
+ *   atomic config set <key> <value> Set configuration value
+ *   atomic --version                Show version
+ *   atomic --help                   Show help
+ */
+
+import { Command } from "@commander-js/extra-typings";
+import { VERSION } from "@/version.ts";
+import { COLORS } from "@/theme/colors.ts";
+import { AGENT_CONFIG, type AgentKey, SCM_CONFIG, type SourceControlType } from "@/services/config/index.ts";
+
+/**
+ * Create and configure the main CLI program
+ */
+export function createProgram() {
+    const program = new Command()
+        .name("atomic")
+        .description("Configuration management CLI for coding agents")
+        .version(VERSION, "-v, --version", "Show version number")
+
+        // Global options available to all commands
+        .option("-f, --force", "Overwrite all config files")
+        .option("-y, --yes", "Auto-confirm all prompts (non-interactive mode)")
+        .option("--no-banner", "Skip ASCII banner display")
+
+        // Configure error output with colors
+        .configureOutput({
+            writeErr: (str) => {
+                process.stderr.write(`${COLORS.red}${str}${COLORS.reset}`);
+            },
+            outputError: (str, write) => {
+                write(`${COLORS.red}${str}${COLORS.reset}`);
+            },
+        });
+
+    // Build agent choices string for help text
+    const agentChoices = Object.keys(AGENT_CONFIG).join(", ");
+    const scmChoices = Object.keys(SCM_CONFIG).join(", ");
+
+    // Add init command
+    program
+        .command("init")
+        .description("Interactive setup with agent selection")
+        .option(
+            "-a, --agent <name>",
+            `Pre-select agent to configure (${agentChoices})`,
+        )
+        .option(
+            "-s, --scm <name>",
+            `Pre-select source control system (${scmChoices})`,
+        )
+        .action(async (localOpts) => {
+            const globalOpts = program.opts();
+            const { initCommand } = await import("@/commands/cli/init.ts");
+
+            await initCommand({
+                showBanner: globalOpts.banner !== false,
+                preSelectedAgent: localOpts.agent as AgentKey | undefined,
+                preSelectedScm: localOpts.scm as SourceControlType | undefined,
+                force: globalOpts.force,
+                yes: globalOpts.yes,
+            });
+        });
+
+    // Add chat command (default command when no subcommand is provided)
+    program
+        .command("chat", { isDefault: true })
+        .description("Start an interactive chat session with a coding agent")
+        .option("-a, --agent <name>", `Agent to chat with (${agentChoices})`)
+        .allowUnknownOption()
+        .allowExcessArguments(true)
+        .addHelpText(
+            "after",
+            `
+All arguments after -a <agent> are forwarded to the native agent CLI.
+
+Examples:
+  $ atomic chat -a claude                           Start Claude interactively
+  $ atomic chat -a copilot                          Start Copilot interactively
+  $ atomic chat -a opencode                         Start OpenCode interactively
+  $ atomic chat -a claude "fix the bug"             Claude with initial prompt
+  $ atomic chat -a copilot --model gpt-4o           Copilot with custom model
+  $ atomic chat -a claude --verbose                 Forward --verbose to claude`,
+        )
+        .action(async (localOpts, cmd) => {
+            const validAgents = Object.keys(AGENT_CONFIG);
+            const agentType = localOpts.agent;
+
+            if (!agentType) {
+                console.error(
+                    `${COLORS.red}Error: Missing agent.${COLORS.reset}`,
+                );
+                console.error(
+                    "Start chat with an explicit provider, for example: atomic chat -a claude",
+                );
+                process.exit(1);
+            }
+
+            // Validate agent choice
+            if (!validAgents.includes(agentType)) {
+                console.error(
+                    `${COLORS.red}Error: Unknown agent '${agentType}'${COLORS.reset}`,
+                );
+                console.error(`Valid agents: ${agentChoices}`);
+                process.exit(1);
+            }
+
+            // Collect extra args/options to forward to the native CLI
+            const passthroughArgs = cmd.args;
+
+            const { chatCommand } = await import("@/commands/cli/chat.ts");
+            const exitCode = await chatCommand({
+                agentType: agentType as "claude" | "opencode" | "copilot",
+                passthroughArgs,
+            });
+
+            process.exit(exitCode);
+        });
+
+    // Add workflow command
+    program
+        .command("workflow")
+        .description("Run a multi-session agent workflow")
+        .option("-n, --name <name>", "Workflow name (matches directory under .atomic/workflows/<name>/)")
+        .option("-a, --agent <name>", `Agent to use (${agentChoices})`)
+        .option("-l, --list", "List available workflows")
+        .argument("[prompt...]", "Prompt for the workflow")
+        .action(async (promptParts, localOpts) => {
+            const { workflowCommand } = await import("@/commands/cli/workflow.ts");
+            const exitCode = await workflowCommand({
+                name: localOpts.name,
+                agent: localOpts.agent,
+                prompt: promptParts.length > 0 ? promptParts.join(" ") : undefined,
+                list: localOpts.list,
+            });
+            process.exit(exitCode);
+        });
+
+    program
+        .command("update")
+        .description("Update atomic to the latest version and reinstall skills")
+        .action(async () => {
+            const { updateCommand } = await import("@/commands/cli/update.ts");
+            process.exit(await updateCommand());
+        });
+
+    // Add config command for managing CLI settings
+    const configCmd = program
+        .command("config")
+        .description("Manage atomic configuration");
+
+    // Add 'set' subcommand to config
+    configCmd
+        .command("set")
+        .description("Set a configuration value")
+        .argument("<key>", "Configuration key (e.g., telemetry)")
+        .argument("<value>", "Value to set (e.g., true, false)")
+        .action(async (key: string, value: string) => {
+            const { configCommand } = await import("@/commands/cli/config.ts");
+            await configCommand("set", key, value);
+        });
+
+    return program;
+}
+
+// Create the program instance for use by main() and tests
+export const program = createProgram();
+
+/**
+ * Main entry point for the CLI
+ */
+async function main(): Promise<void> {
+    try {
+        // Parse and execute the command
+        await program.parseAsync();
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`${COLORS.red}Error: ${message}${COLORS.reset}`);
+        process.exit(1);
+    }
+}
+
+// Run the CLI
+if (import.meta.main) {
+    await main();
+}

package/src/commands/cli/chat/client.ts

@@ -0,0 +1,18 @@
+/**
+ * Chat client utilities
+ *
+ * Provides agent display name resolution for the chat command.
+ * SDK client creation has been removed — the chat command now spawns
+ * native agent CLIs directly.
+ */
+
+import type { AgentKey } from "@/services/config/index.ts";
+
+export function getAgentDisplayName(agentType: AgentKey): string {
+  const names: Record<AgentKey, string> = {
+    claude: "Claude",
+    opencode: "OpenCode",
+    copilot: "Copilot",
+  };
+  return names[agentType] ?? agentType;
+}

package/src/commands/cli/chat/index.ts

@@ -0,0 +1,247 @@
+#!/usr/bin/env bun
+/**
+ * Chat CLI command for atomic
+ *
+ * Spawns the native agent CLI as an interactive subprocess.
+ * When already inside a tmux/psmux session, the agent spawns inline
+ * in the current pane. When outside tmux, it creates a new tmux
+ * session and attaches to it.
+ *
+ * All extra arguments after `-a <agent>` are forwarded to the native CLI.
+ *
+ * Usage:
+ *   atomic chat -a <agent> [native-args...]
+ */
+
+import { join } from "path";
+import { homedir } from "os";
+import { mkdir, writeFile, rm } from "fs/promises";
+import { AGENT_CONFIG, type AgentKey } from "@/services/config/index.ts";
+import { COLORS } from "@/theme/colors.ts";
+import { isCommandInstalled } from "@/services/system/detect.ts";
+import {
+  ensureAtomicGlobalAgentConfigs,
+} from "@/services/config/atomic-global-config.ts";
+import { getConfigRoot } from "@/services/config/config-path.ts";
+import {
+  isInsideTmux,
+  isTmuxInstalled,
+  resetMuxBinaryCache,
+} from "@/sdk/workflows.ts";
+import {
+  createSession,
+  killSession,
+  getMuxBinary,
+} from "@/sdk/workflows.ts";
+import { ensureTmuxInstalled } from "@/lib/spawn.ts";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type AgentType = AgentKey;
+
+/**
+ * Options for the chat command.
+ */
+export interface ChatCommandOptions {
+  /** Agent type to use (claude, opencode, copilot) */
+  agentType?: AgentType;
+  /** Extra args/options forwarded verbatim to the native agent CLI */
+  passthroughArgs?: string[];
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+export function getAgentDisplayName(agentType: AgentType): string {
+  return AGENT_CONFIG[agentType].name;
+}
+
+/**
+ * Build the argv array for spawning the agent CLI.
+ *
+ * Starts with the agent's default chat_flags, then appends any
+ * extra args the user passed after `-a <agent>`.
+ */
+export function buildAgentArgs(agentType: AgentType, passthroughArgs: string[] = []): string[] {
+  const config = AGENT_CONFIG[agentType];
+  return [...config.chat_flags, ...passthroughArgs];
+}
+
+function generateChatId(): string {
+  return crypto.randomUUID().slice(0, 8);
+}
+
+/** Escape a string for safe interpolation inside a bash double-quoted string. */
+function escBash(s: string): string {
+  return s.replace(/[\\"$`!]/g, "\\$&");
+}
+
+/** Escape a string for safe interpolation inside a PowerShell double-quoted string. */
+function escPwsh(s: string): string {
+  return s.replace(/[`"$]/g, "`$&");
+}
+
+/**
+ * Build a launcher script that preserves cwd and properly quotes args.
+ * This avoids shell-injection risks from passthrough args.
+ */
+function buildLauncherScript(
+  cmd: string,
+  args: string[],
+  projectRoot: string,
+): { script: string; ext: string } {
+  const isWin = process.platform === "win32";
+
+  if (isWin) {
+    // PowerShell: use array splatting for safe arg passing
+    const argList = args.map((a) => `"${escPwsh(a)}"`).join(", ");
+    const script = [
+      `Set-Location "${escPwsh(projectRoot)}"`,
+      argList.length > 0
+        ? `& "${escPwsh(cmd)}" @(${argList})`
+        : `& "${escPwsh(cmd)}"`,
+    ].join("\n");
+    return { script, ext: "ps1" };
+  }
+
+  // Bash: use proper quoting for each arg
+  const quotedArgs = args
+    .map((a) => `"${escBash(a)}"`)
+    .join(" ");
+  const script = [
+    "#!/bin/bash",
+    `cd "${escBash(projectRoot)}"`,
+    `exec "${escBash(cmd)}" ${quotedArgs}`,
+  ].join("\n");
+  return { script, ext: "sh" };
+}
+
+// ============================================================================
+// Chat Command Implementation
+// ============================================================================
+
+/**
+ * Spawn the native agent CLI as an interactive subprocess.
+ *
+ * When running inside a tmux/psmux session, the agent spawns inline
+ * in the current pane with inherited stdio.
+ *
+ * When running outside tmux, a new tmux session is created and
+ * attached so the agent benefits from multiplexer features.
+ *
+ * @param options - Chat command configuration options
+ * @returns Exit code from the agent process
+ */
+export async function chatCommand(options: ChatCommandOptions = {}): Promise<number> {
+  const { agentType, passthroughArgs } = options;
+
+  if (!agentType) {
+    throw new Error("agentType is required. Start chat with `atomic chat -a <agent>`.");
+  }
+
+  const config = AGENT_CONFIG[agentType];
+
+  // Check the agent CLI is installed
+  if (!isCommandInstalled(config.cmd)) {
+    console.error(
+      `${COLORS.red}Error: '${config.cmd}' is not installed or not in PATH.${COLORS.reset}`
+    );
+    console.error(`Install it from: ${config.install_url}`);
+    return 1;
+  }
+
+  // ── Preflight: global config sync ──
+  const projectRoot = process.cwd();
+  const configRoot = getConfigRoot();
+
+  await ensureAtomicGlobalAgentConfigs(configRoot);
+
+  // ── Build argv ──
+  const args = buildAgentArgs(agentType, passthroughArgs);
+  const cmd = [config.cmd, ...args];
+
+  // ── Inside tmux: spawn inline in the current pane ──
+  if (isInsideTmux()) {
+    return spawnDirect(cmd, projectRoot);
+  }
+
+  // ── No TTY: tmux attach requires a real terminal ──
+  if (!process.stdin.isTTY) {
+    return spawnDirect(cmd, projectRoot);
+  }
+
+  // ── Ensure tmux is available ──
+  if (!isTmuxInstalled()) {
+    console.log("Terminal multiplexer not found. Installing...");
+    try {
+      await ensureTmuxInstalled();
+      resetMuxBinaryCache();
+    } catch {
+      // Fall through to check below
+    }
+    if (!isTmuxInstalled()) {
+      // No tmux available — fall back to direct spawn
+      return spawnDirect(cmd, projectRoot);
+    }
+  }
+
+  // ── Build launcher script for safe arg/cwd handling ──
+  const chatId = generateChatId();
+  const windowName = `atomic-chat-${chatId}`;
+
+  const sessionsDir = join(homedir(), ".atomic", "sessions", "chat");
+  await mkdir(sessionsDir, { recursive: true });
+  const { script, ext } = buildLauncherScript(config.cmd, args, projectRoot);
+  const launcherPath = join(sessionsDir, `${windowName}.${ext}`);
+  await writeFile(launcherPath, script, { mode: 0o755 });
+
+  const shellCmd = process.platform === "win32"
+    ? `pwsh -NoProfile -File "${launcherPath}"`
+    : `bash "${launcherPath}"`;
+
+  // ── Outside tmux: create a new session and attach ──
+  try {
+    createSession(windowName, shellCmd, undefined, projectRoot);
+
+    const muxBinary = getMuxBinary() ?? "tmux";
+    const attachProc = Bun.spawn([muxBinary, "attach-session", "-t", windowName], {
+      stdio: ["inherit", "inherit", "inherit"],
+    });
+    const exitCode = await attachProc.exited;
+
+    // Clean up launcher
+    try { await rm(launcherPath, { force: true }); } catch {}
+
+    // If tmux attach itself failed (e.g. lost TTY), clean up and fall back
+    if (exitCode !== 0) {
+      try { killSession(windowName); } catch {}
+      return spawnDirect(cmd, projectRoot);
+    }
+
+    return exitCode;
+  } catch (error) {
+    try { await rm(launcherPath, { force: true }); } catch {}
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(
+      `${COLORS.yellow}Warning: Failed to create tmux session (${message}). Falling back to direct spawn.${COLORS.reset}`
+    );
+    return spawnDirect(cmd, projectRoot);
+  }
+}
+
+/**
+ * Spawn the agent CLI directly with inherited stdio.
+ * Used when not inside tmux.
+ */
+async function spawnDirect(cmd: string[], projectRoot: string): Promise<number> {
+  const proc = Bun.spawn(cmd, {
+    stdio: ["inherit", "inherit", "inherit"],
+    cwd: projectRoot,
+    env: { ...process.env },
+  });
+
+  return await proc.exited;
+}

package/src/commands/cli/chat.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env bun
+/**
+ * Compatibility barrel for the chat CLI command.
+ *
+ * The implementation lives under `commands/cli/chat/`.
+ */
+
+export * from "@/commands/cli/chat/index.ts";

package/src/commands/cli/config.ts

@@ -0,0 +1,55 @@
+/**
+ * Config command - Manage Atomic CLI configuration
+ *
+ * Usage: atomic config set <key> <value>
+ *
+ * Currently supported:
+ *   atomic config set telemetry true|false
+ */
+
+import { log } from "@clack/prompts";
+import { setTelemetryEnabled } from "@/services/config/settings.ts";
+
+/**
+ * Execute the config command
+ */
+export async function configCommand(
+  subcommand: string | undefined,
+  key: string | undefined,
+  value: string | undefined
+): Promise<void> {
+  if (!subcommand) {
+    log.error("Missing subcommand. Usage: atomic config set <key> <value>");
+    process.exit(1);
+  }
+
+  if (subcommand !== "set") {
+    log.error(`Unknown subcommand: ${subcommand}. Only 'set' is supported.`);
+    process.exit(1);
+  }
+
+  if (!key) {
+    log.error("Missing key. Usage: atomic config set <key> <value>");
+    process.exit(1);
+  }
+
+  if (key !== "telemetry") {
+    log.error(`Unknown config key: ${key}. Only 'telemetry' is supported.`);
+    process.exit(1);
+  }
+
+  if (!value) {
+    log.error("Missing value. Usage: atomic config set telemetry <true|false>");
+    process.exit(1);
+  }
+
+  if (value !== "true" && value !== "false") {
+    log.error(`Invalid value: ${value}. Must be 'true' or 'false'.`);
+    process.exit(1);
+  }
+
+  const enabled = value === "true";
+  setTelemetryEnabled(enabled);
+
+  log.success(`Telemetry has been ${enabled ? "enabled" : "disabled"}.`);
+}