@guildai/cli 0.6.2 → 0.7.1

package/README.md

@@ -229,6 +229,8 @@ guild version                           # Show version info
 ```bash
 guild setup                             # Install skills + configure MCP server
 guild setup --claude-md                 # Also create a CLAUDE.md template
+guild setup --codex                     # Install Codex skills + configure MCP server
+guild setup --codex --agents-md         # Also create an AGENTS.md template
 guild setup --no-mcp                    # Install skills only, skip MCP configuration
 guild mcp                               # Start MCP server (used by Claude Code, etc.)
 ```
@@ -243,7 +245,7 @@ The CLI includes an [MCP](https://modelcontextprotocol.io/) server that exposes
 guild setup
 ```
 
-This installs Claude Code skills and adds a `guild` entry to `.mcp.json` in your project. Claude Code (and other MCP-compatible tools) will automatically connect when they detect it.
+This installs Claude Code skills and adds a `guild` entry to `.mcp.json` in your project. Use `guild setup --codex` to install Codex skills instead. Claude Code and other MCP-compatible tools will automatically connect when they detect `.mcp.json`.
 
 **What it provides:**
 

package/dist/commands/agent/chat.js

@@ -5,7 +5,7 @@ import { render } from 'ink';
 import React from 'react';
 import open from 'open';
 import { hyperlink } from '../../lib/colors.js';
-import { getAgentId, readAgentFiles } from '../../lib/agent-helpers.js';
+import { getAgentId, readAgentFiles, buildEphemeralVersion, BuildTimeoutError, BuildFailedError, } from '../../lib/agent-helpers.js';
 import { ChatApp, createSession, ensureAuthenticated } from '../chat.js';
 import { readFileSync } from 'fs';
 import path from 'path';
@@ -15,8 +15,6 @@ import { isQuietMode, getOutputMode } from '../../lib/output-mode.js';
 import { handleAxiosError, ErrorCodes } from '../../lib/errors.js';
 import { format } from '../../lib/progress.js';
 import { showBetaGuidance } from '../../lib/auth.js';
-import { pollUntilComplete } from '../../lib/polling.js';
-import { runGit } from '../../lib/git.js';
 import { suppressScrollbackClear } from '../../lib/alternate-screen.js';
 import * as readline from 'readline';
 import { pollForResponse } from '../../lib/session-polling.js';
@@ -32,13 +30,14 @@ export function createAgentChatCommand() {
         .description('Chat with the agent in current directory')
         .argument('[prompt...]', 'Optional initial prompt for the agent')
         .option('--path <dir>', 'Path to agent directory (defaults to current directory)')
-        .option('--workspace <identifier>', 'Workspace ID or full name (e.g., owner/workspace-name)')
+        .option('--workspace <identifier>', 'Workspace ID or full name (e.g., owner~workspace-name)')
         .option('--mode <format>', 'Input mode: json (one-shot) or jsonl (line-by-line)')
-        .option('--ephemeral', 'Chat using unsaved changes (no guild agent save required)')
+        .option('--agent-version <id>', 'Chat with a specific version (UUID or version number)')
         .option('--no-splash', 'Skip the splash screen animation')
         .option('--resume <session-id>', 'Resume an existing session')
         .option('--open', 'Open session in web dashboard')
-        .addHelpText('after', '\nTo chat with a published agent by name: guild chat --agent owner/agent-name')
+        .option('--no-cache', 'Skip ephemeral build cache (force a fresh build)')
+        .addHelpText('after', '\nTo chat with a published agent by name: guild chat --agent owner~agent-name')
         .action(async (promptArgs, options) => {
         try {
             // Get agent ID from guild.json in the specified path
@@ -67,106 +66,36 @@ export function createAgentChatCommand() {
             const quiet = isQuietMode();
             const resolvedPath = path.resolve(agentPath);
             // Resolve the version to chat with.
-            // Default: use the latest saved version (requires clean working tree).
-            // --ephemeral: read local files and create an ephemeral version.
+            // Default: create ephemeral version from working directory.
+            // --version: use a specific existing version.
             let version;
-            if (options.ephemeral) {
-                if (!quiet) {
-                    console.error('Building agent...');
-                }
-                const agentFiles = await readAgentFiles(resolvedPath);
-                version = (await client.post(`/agents/${agentId}/versions`, {
-                    files: agentFiles,
-                    summary: '[Chat] Ephemeral development version',
-                    version_type: 'EPHEMERAL',
-                }));
-            }
-            else {
-                // Require clean working tree
-                const { stdout: statusOutput } = await runGit(['status', '--porcelain'], {
-                    cwd: resolvedPath,
-                });
-                if (statusOutput.trim().length > 0) {
-                    console.error('Error: Working tree has unsaved changes');
-                    console.error('');
-                    console.error('Options:');
-                    console.error('  1. Save your changes first:');
-                    console.error('       guild agent save --message "your changes"');
-                    console.error('');
-                    console.error('  2. Chat with unsaved changes:');
-                    console.error('       guild agent chat --ephemeral');
-                    process.exit(1);
-                }
-                // Get commit SHA and look for an existing version
-                const { stdout: shaOutput } = await runGit(['rev-parse', 'HEAD'], {
-                    cwd: resolvedPath,
-                });
-                const commitSha = shaOutput.trim();
+            let ephemeralCached = false;
+            if (options.agentVersion) {
+                // Explicit version: look it up by ID or version number
                 const existingVersions = (await client.get(`/agents/${agentId}/versions`));
-                const existing = existingVersions.items.find((v) => v.sha === commitSha);
-                if (existing) {
-                    version = existing;
-                }
-                else {
-                    if (!quiet) {
-                        console.error('Building agent...');
-                    }
-                    version = (await client.post(`/agents/${agentId}/versions`, {
-                        commit_sha: commitSha,
-                        summary: '[Chat] Development version',
-                        version_type: 'COMMITTED',
-                    }));
-                }
-            }
-            // Wait for build to complete (skip if version already validated)
-            if (version.validation_status === 'PENDING' ||
-                version.validation_status === 'RUNNING') {
-                const pollResult = await pollUntilComplete({
-                    resourceId: version.id,
-                    endpoint: `/versions/${version.id}`,
-                    isComplete: (response) => response.validation_status !== 'PENDING' &&
-                        response.validation_status !== 'RUNNING',
-                    message: 'Building...',
-                    successMessage: 'Build finished',
-                    timeoutMessage: 'Build timed out',
-                    maxAttempts: 120,
-                    delayMs: 1000,
-                });
-                if (!pollResult.success || !pollResult.response) {
-                    console.error('Error: Agent build did not complete');
+                const match = existingVersions.items.find((v) => v.id === options.agentVersion ||
+                    v.version_number === options.agentVersion);
+                if (!match) {
+                    console.error(`Error: Version not found: ${options.agentVersion}`);
+                    console.error('');
+                    console.error('List available versions:');
+                    console.error(`  guild agent versions ${agentId}`);
                     process.exit(1);
                 }
-                version = pollResult.response;
+                version = match;
             }
-            if (version.validation_status === 'FAILED') {
-                console.error('Error: Agent build failed');
-                console.error('');
-                // Fetch validation steps to show the actual error
-                try {
-                    const stepsResponse = await client.get(`/versions/${version.id}/validation/steps`);
-                    const failedSteps = stepsResponse.steps.filter((step) => step.status === 'FAILED');
-                    if (failedSteps.length > 0) {
-                        for (const step of failedSteps) {
-                            console.error(`Step "${step.name}" failed:`);
-                            if (step.content) {
-                                console.error(step.content);
-                            }
-                            console.error('');
-                        }
-                    }
-                    else {
-                        console.error('No failed steps found. Check validation logs for details.');
-                        console.error('');
-                    }
+            else {
+                if (!quiet) {
+                    console.error('Building agent...');
                 }
-                catch {
-                    // If we can't fetch steps, just show generic message
-                    console.error('Could not fetch validation details.');
-                    console.error('');
+                const agentFiles = await readAgentFiles(resolvedPath);
+                const noCache = options.cache === false;
+                const result = await buildEphemeralVersion(client, agentId, agentFiles, resolvedPath, '[Chat] Ephemeral development version', { noCache });
+                version = result.version;
+                ephemeralCached = result.cached;
+                if (ephemeralCached && !quiet) {
+                    console.error('No changes detected, reusing cached build.');
                 }
-                console.error('Fix the issues and retry:');
-                console.error(`  guild agent chat ${agentId}`);
-                process.exit(1);
             }
             // Branch: JSON/JSONL modes vs interactive
             if (options.mode === 'json' || options.mode === 'jsonl') {
@@ -299,6 +228,19 @@ export function createAgentChatCommand() {
             }
         }
         catch (error) {
+            if (error instanceof BuildTimeoutError) {
+                console.error('Error: Build did not complete');
+                console.error('');
+                console.error(error.message);
+                console.error('');
+                console.error('Check build status:');
+                console.error('  guild agent versions');
+                process.exit(1);
+            }
+            if (error instanceof BuildFailedError) {
+                console.error(`Error: ${error.message}`);
+                process.exit(1);
+            }
             const formattedError = handleAxiosError(error);
             if (formattedError.code === ErrorCodes.AUTH_REQUIRED ||
                 formattedError.code === ErrorCodes.AUTH_TOKEN_INVALID) {

package/dist/commands/agent/clone.js

@@ -23,7 +23,7 @@ export function createAgentCloneCommand() {
     const cmd = new Command('clone');
     cmd
         .description('Clone an existing agent repository')
-        .argument('<identifier>', 'Agent ID or full name to clone (e.g., owner/agent-name)')
+        .argument('<identifier>', 'Agent ID or full name to clone (e.g., owner~agent-name)')
         .option('--directory <path>', 'Target directory for clone')
         .option('--force', 'Clone even if directory is not empty', false)
         .action(async (agentId, options) => {

package/dist/commands/agent/code.js

@@ -11,7 +11,7 @@ export function createAgentCodeCommand() {
     const cmd = new Command('code');
     cmd
         .description('Fetch the latest code for an agent')
-        .argument('[identifier]', 'Agent ID or full name (e.g., owner/agent-name)')
+        .argument('[identifier]', 'Agent ID or full name (e.g., owner~agent-name)')
         .option('--draft', 'Include draft versions (default: only published)', false)
         .option('--output <directory>', 'Write files to directory instead of printing JSON')
         .action(async (agentIdArg, options) => {

package/dist/commands/agent/fork.js

@@ -48,7 +48,7 @@ export function createAgentForkCommand() {
     const cmd = new Command('fork');
     cmd
         .description('Fork an existing agent version to create a new agent')
-        .argument('[identifier]', 'Agent ID, full name, or agent:version (e.g., owner/agent-name:version_xyz)')
+        .argument('[identifier]', 'Agent ID, full name, or agent:version (e.g., owner~agent-name:version_xyz)')
         .option('--name <name>', 'Name for the forked agent')
         .option('--description <desc>', 'Description for the forked agent')
         .option('--directory <path>', 'Target directory for clone')
@@ -65,7 +65,7 @@ export function createAgentForkCommand() {
                 const agentPart = identifierArg.substring(0, colonIndex);
                 sourceVersionId = identifierArg.substring(colonIndex + 1);
                 if (!agentPart || !sourceVersionId) {
-                    output.error('Error: Invalid argument format', 'Expected: [identifier] or [identifier]:[version-id]\nExample: guild agent fork owner/agent-name:version_xyz\n\nTo find versions:\n  guild agent versions <agent-id>');
+                    output.error('Error: Invalid argument format', 'Expected: [identifier] or [identifier]:[version-id]\nExample: guild agent fork owner~agent-name:version_xyz\n\nTo find versions:\n  guild agent versions <agent-id>');
                     process.exit(1);
                 }
                 const resolved = await getAgentId(agentPart);

package/dist/commands/agent/get.js

@@ -10,7 +10,7 @@ export function createAgentGetCommand() {
     const cmd = new Command('get');
     cmd
         .description('Get agent details')
-        .argument('[identifier]', 'Agent ID or full name (e.g., owner/agent-name)')
+        .argument('[identifier]', 'Agent ID or full name (e.g., owner~agent-name)')
         .action(async (idArg) => {
         const output = createOutputWriter();
         try {

package/dist/commands/agent/grep.js

@@ -94,10 +94,10 @@ async function grepAllAgents(client, patternRE, publishedOnly, output) {
             }
             catch (ex) {
                 const formattedError = handleAxiosError(ex);
-                output.error(`${agent.owner?.name}/${agent.name}: ${formattedError.details}`);
+                output.error(`${agent.owner?.name}~${agent.name}: ${formattedError.details}`);
                 return;
             }
-            searchFiles(files, patternRE, `${agent.owner?.name}/${agent.name}/`, output);
+            searchFiles(files, patternRE, `${agent.owner?.name}~${agent.name}/`, output);
         }));
         offset += response.pagination.limit;
         if (!response.pagination.has_more)

package/dist/commands/agent/init.js

@@ -319,17 +319,24 @@ export function createAgentInitCommand() {
             };
             await fs.writeFile(guildJsonPath, JSON.stringify(guildConfig, null, 2) + '\n', 'utf-8');
             steps.succeed('Create guild.json');
-            // Add guild.json to .gitignore if not already present
+            // Add guild.json and .guild/cache/ to .gitignore if not already present
             const gitignorePath = path.join(targetDir, '.gitignore');
             try {
                 const gitignoreContent = await fs.readFile(gitignorePath, 'utf-8');
+                let additions = '';
                 if (!gitignoreContent.includes('guild.json')) {
-                    await fs.appendFile(gitignorePath, '\nguild.json\n');
+                    additions += '\nguild.json\n';
+                }
+                if (!gitignoreContent.includes('.guild/cache/')) {
+                    additions += '.guild/cache/\n';
+                }
+                if (additions) {
+                    await fs.appendFile(gitignorePath, additions);
                 }
             }
             catch {
                 // .gitignore doesn't exist (backend should have created it), create it
-                await fs.writeFile(gitignorePath, 'guild.json\n');
+                await fs.writeFile(gitignorePath, 'guild.json\n.guild/cache/\n');
             }
             // Install pre-push hook to block direct git push
             await installPrePushHook(targetDir);

package/dist/commands/agent/list.js

@@ -3,7 +3,7 @@
 import { Command } from 'commander';
 import { GuildAPIClient } from '../../lib/api-client.js';
 import { getAuthToken } from '../../lib/auth.js';
-import { handleAxiosError } from '../../lib/errors.js';
+import { handleAxiosError, ErrorCodes } from '../../lib/errors.js';
 import { getOutputMode } from '../../lib/output-mode.js';
 import { createOutputWriter, formatAgentTable } from '../../lib/output.js';
 const SORT_MAP = {
@@ -19,6 +19,7 @@ export function createAgentListCommand() {
         .option('--search <query>', 'Search agents by name or description')
         .option('--sort <field>', 'Sort by: updated, newest, name, popular (default: updated)', 'updated')
         .option('--published', 'Only show published agents')
+        .option('--workspace <id>', 'Filter agents by workspace ID or name')
         .option('--limit <number>', 'Number of results to return', '20')
         .option('--offset <number>', 'Offset for pagination', '0')
         .action(async (options) => {
@@ -39,6 +40,9 @@ export function createAgentListCommand() {
             if (options.published) {
                 params.append('published_only', 'true');
             }
+            if (options.workspace) {
+                params.append('for_workspace', options.workspace);
+            }
             const sortField = SORT_MAP[options.sort];
             if (sortField) {
                 params.append('sort_by', sortField);
@@ -53,6 +57,10 @@ export function createAgentListCommand() {
         }
         catch (error) {
             const formattedError = handleAxiosError(error);
+            if (formattedError.code === ErrorCodes.NOT_FOUND) {
+                output.error('Workspace not found');
+                process.exit(1);
+            }
             output.error(`Failed to list agents: ${formattedError.details}`);
             process.exit(1);
         }

package/dist/commands/agent/publish.js

@@ -10,7 +10,7 @@ export function createAgentPublishCommand() {
     const cmd = new Command('publish');
     cmd
         .description('Publish the latest draft version of an agent')
-        .argument('[identifier]', 'Agent ID or full name (e.g., owner/agent-name)')
+        .argument('[identifier]', 'Agent ID or full name (e.g., owner~agent-name)')
         .option('--wait', 'Wait for validation to complete before publishing')
         .action(async (agentIdArg, options) => {
         const output = createOutputWriter();

package/dist/commands/agent/revalidate.js

@@ -10,7 +10,7 @@ export function createAgentRevalidateCommand() {
     const cmd = new Command('revalidate');
     cmd
         .description('Revalidate an agent version')
-        .argument('[identifier]', 'Agent ID or full name (e.g., owner/agent-name)')
+        .argument('[identifier]', 'Agent ID or full name (e.g., owner~agent-name)')
         .argument('[version-id]', 'ID of the version to revalidate (uses latest if omitted)')
         .action(async (agentIdArg, versionIdArg) => {
         const output = createOutputWriter();

package/dist/commands/agent/save.js

@@ -44,6 +44,7 @@ export function createAgentSaveCommand() {
             output.error('Commit message is required with --all', 'Provide a message describing your changes:\n  guild agent save -A --message "Add new feature"');
             process.exit(1);
         }
+        let versionNumber;
         try {
             // Check for guild.json
             const guildJsonPath = path.join(cwd, 'guild.json');
@@ -88,8 +89,22 @@ export function createAgentSaveCommand() {
                 }
                 packageJson.version = newVersion;
                 await fs.writeFile(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n');
+                versionNumber = newVersion;
                 output.progress(`✓ Bumped version: ${currentVersion} → ${newVersion}`);
             }
+            else {
+                // No bump — read version from package.json if it exists
+                const packageJsonPath = path.join(cwd, 'package.json');
+                try {
+                    const pkg = JSON.parse(await fs.readFile(packageJsonPath, 'utf-8'));
+                    if (pkg.version) {
+                        versionNumber = pkg.version;
+                    }
+                }
+                catch {
+                    // No package.json or unreadable — version stays undefined
+                }
+            }
             // Check for uncommitted changes and unpushed commits
             const { stdout: statusOutput } = await runGit(['status', '--porcelain'], {
                 cwd,
@@ -249,13 +264,19 @@ export function createAgentSaveCommand() {
             const commitSha = shaOutput.trim();
             // Create version in guildcore (always as DRAFT, publish happens separately)
             const client = new GuildAPIClient();
-            let version = await client.post(`/agents/${guildConfig.agent_id}/versions`, {
+            const agentId = guildConfig?.agent_id;
+            if (!agentId) {
+                output.error('Not in an agent directory');
+                process.exit(1);
+            }
+            let version = await client.post(`/agents/${agentId}/versions`, {
                 commit_sha: commitSha,
                 summary: versionMessage,
                 version_type: 'COMMITTED',
+                ...(versionNumber ? { version_number: versionNumber } : {}),
             });
             output.progress(`✓ Created version (${version.id})`);
-            if (options.wait) {
+            if (options.wait || options.publish) {
                 version = await waitForValidation(version.id, output);
             }
             if (options.publish) {