CLI: Add persistent shell mode to CLI with workspace management

[stennkool]

Persistent Shell Mode Implementation

Context

Implemented persistent shell mode for the Kilocode CLI, allowing users to:

• Execute shell commands with maintained state (current working directory, environment variables)
• Change directories within the shell and have those changes persist across commands
• Automatically update the CLI's workspace and reinitialize the AI context when exiting shell mode
• Navigate command history and interact seamlessly with the shell interface

Implementation

Architecture Overview

Core Components:

1. ShellSession Service (cli/src/services/shell/session.ts)

   • Spawns a persistent shell process using child_process.spawn
   • Maintains shell state across command executions
   • Uses sentinel-based output parsing (__KILO_DONE__:exitCode:cwd) to reliably detect command completion and track directory changes
   • Implements timeout handling and error recovery

2. Shell State Management (cli/src/state/atoms/shell.ts)

   • shellSessionAtom: Holds the persistent ShellSession instance
   • currentShellDirectoryAtom: Tracks the shell's current working directory
   • initializeShellSessionAtom: Action atom to initialize the shell session when entering shell mode
   • disposeShellSessionAtom: Action atom to clean up the shell session on exit
   • applyShellWorkspaceAtom: Action atom to propagate shell's CWD back to the CLI workspace
   • executeShellCommandAtom: Refactored to use persistent session instead of child_process.exec

3. Workspace Propagation (cli/src/cli.ts)

   • handleWorkspaceChange(): Method that handles workspace changes from shell mode
   • Disposes and recreates the ExtensionService with the new workspace
   • Reinitializes AI context and configuration
   • Updates telemetry context
   • Provides user feedback during the transition

4. UI Integration (cli/src/ui/UI.tsx)

   • Monitors workspacePathAtom for changes
   • Triggers onWorkspaceChange callback when the shell's directory differs from the CLI's workspace
   • Ensures smooth workspace updates without requiring manual intervention

Key Design Decisions

• Sentinel-Based Output Parsing: Instead of relying on shell prompts or environment variables that might vary, we wrap each command with a unique sentinel (__KILO_DONE__:exitCode:cwd) to reliably detect completion
• Persistent Child Process: Uses spawn() rather than exec() to maintain a long-lived shell, preserving environment and working directory between commands
• Atomic Workspace Updates: When exiting shell mode, workspace changes are atomic—the CLI updates both process.cwd() and the workspace atom simultaneously
• Error Handling: Comprehensive error handling with user-visible messages during workspace transitions and failed operations
• Type Safety: Introduced proper TypeScript types for mock objects in tests to avoid any types

Tradeoffs

• Uses as unknown as type casting to access private telemetry fields (pragmatic solution given singleton pattern)
• Periodic polling (100ms) in UI to detect workspace changes (simple but not reactive; could be improved with event emitters)
• Sentinel approach adds slight overhead to each command but ensures reliability across all shell types

How to Test

1. Start Kilo Code CLI:

   cd /your/project
   kilocode

2. Enter Shell Mode:

   • Press Shift+! or type ! when the input is empty
   • You should see the input mode change to shell mode

3. Test Directory Navigation:

   • Type cd /tmp and press Enter
   • Type pwd and verify you're in /tmp
   • Type cd /var and press Enter
   • Type pwd again—should show /var

4. Test Environment Variables:

   • Type export MY_VAR=hello and press Enter
   • Type echo $MY_VAR and verify it prints hello

5. Exit Shell Mode and Verify Workspace Update:

   • Press Shift+! again to exit shell mode
   • You should see a message: 📁 Workspace changed to: /var\nReinitializing AI context...
   • The CLI should now be operating in the /var workspace
   • Verify by running a command that requires workspace context

6. Test Command History:

   • In shell mode, use up/down arrow keys to navigate previous commands
   • Verify history persists across shell sessions

7. Test Error Handling:

   • Try running a command that fails (e.g., false)
   • Verify exit code is captured correctly
   • Try accessing a non-existent directory: cd /nonexistent
   • Verify error message is displayed

Get in Touch

If you have questions about this implementation, feel free to respond to this PR.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 53b700d

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR