Skip to main content

​
nut code

Start implementing a task using an AI assistant in terminal mode. 
nut code [options] <task-id>
Arguments:
  • task-id - The task ID to implement (e.g., task-000001)
Options:
  • --model <model> - AI agent to use (claude, gemini, codex, droid, kiro) (default: “claude”)
  • --context-type <type> - Context type (change-task, prepare-task, skill, general) (default: “change-task”)
  • --api <url> - API base URL (default: “http://localhost:3000”)
  • --autonomous - Dangerously skip permissions (if available)
  • --auto - Alias for --autonomous
  • --custom-instructions <instructions> - Custom instructions for the agent
  • --new-worktree - Create a new git worktree for this session
  • --worktree-suffix <suffix> - Append a custom suffix to the generated worktree branch
  • --worktree-branch <name> - Override the generated worktree branch name entirely
  • --no-interactive - Run in non-interactive mode (agent exits when done)

​
Overview

The code command launches an interactive AI coding session in your terminal to help you implement a specific task. The AI assistant understands your codebase, the task’s intent, and can help write, modify, and review code.

​
Usage

Start coding on a task: 
# Basic usage
nut code task-000001

# Use a specific AI agent
nut code task-000001 --model claude
nut code task-000001 --model gemini
nut code task-000001 --model codex

# Specify a context type
nut code task-000001 --context-type change-task
nut code task-000001 --context-type prepare-task

# Autonomous mode (skip permission prompts)
nut code task-000001 --autonomous
nut code task-000001 --auto

# Non-interactive mode (agent exits when done)
nut code task-000001 --no-interactive

# With custom instructions
nut code task-000001 --custom-instructions "Focus on performance optimization"

# Create a git worktree for isolated development
nut code task-000001 --new-worktree
nut code task-000001 --new-worktree --worktree-suffix feature
nut code task-000001 --worktree-branch my-custom-branch

# Connect to remote instance
nut code task-000001 --api https://my-coconut.example.com
Make sure you’ve created a task first using nut task create. You can find task IDs (e.g., task-000001) with nut task list.

​
What Happens

When you run nut code:
  1. Loads the task - The AI reads the task description and understands what needs to be done
  2. Analyzes your codebase - Reviews relevant files and project structure
  3. Starts interactive session - Opens a terminal interface where you can chat with the AI
  4. Implements changes - The AI suggests and applies code changes with your approval
  5. Tracks progress - Updates the task status as work progresses

​
Interactive Session

Once the session starts, you can:
  • Ask questions about implementation approaches
  • Request code changes by describing what you need
  • Review suggestions before they’re applied
  • Iterate on solutions until you’re satisfied
  • Run tests to verify changes work correctly

​
Example Workflow

1

Create a task

nut task create "Add user search functionality"
2

Start coding

nut code task-000001
3

Interact with AI

The AI assistant will help you:
  • Plan the implementation
  • Write the necessary code
  • Create or update tests
  • Review and refine changes
4

Complete implementation

Once finished, the AI will mark the task as implemented and you can commit the changes.

​
Tips for Success

Clear, detailed requests help the AI understand exactly what you want. Instead of “add a search”, try “add a search function that queries users by email and username”.
Always review the AI’s suggested changes before accepting them. You’re in control of what gets applied to your codebase.
Work in small steps rather than asking for everything at once. This makes it easier to verify each change.
Keep your code committed in git so you can easily revert changes if needed.

​
Advanced Options

​
Git Worktrees

The --new-worktree option creates an isolated git worktree for your coding session. This allows you to work on a task in a separate directory without affecting your main working tree. 
# Create a worktree automatically
nut code task-000001 --new-worktree

# Worktree will be created at: ../repo-worktree-task-000001/
Benefits of using worktrees:
  • Keep your main branch clean while experimenting
  • Easy to abandon changes if needed
  • Work on multiple tasks simultaneously in different directories

​
Autonomous Mode

Use with caution: Autonomous mode (--autonomous or --auto) allows the AI to make changes without asking for permission. Only use this in safe environments or for well-scoped tasks.
# Enable autonomous mode
nut code task-000001 --autonomous

​
Context Types

The --context-type option controls what context the AI agent receives when starting the session:
  • change-task (default) - Standard implementation context for making code changes
  • prepare-task - Context focused on preparing and planning the task
  • skill - Context tailored for skill-based operations
  • general - General-purpose context without task-specific framing
nut code task-000001 --context-type prepare-task

​
Non-Interactive Mode

Use --no-interactive to run the agent without an interactive session. The agent will complete the task and exit automatically, which is useful for CI/CD pipelines or automated workflows. 
nut code task-000001 --no-interactive

​
Custom Instructions

Provide specific guidance to the AI for this session: 
nut code task-000001 --custom-instructions "Use functional programming patterns and avoid mutations"
nut code task-000001 --custom-instructions "Prioritize code readability over performance"

​
Remote Instances

Connect to a Coconut instance running on a different machine or server: 
nut code task-000001 --api https://coconut.mycompany.com
nut code task-000001 --api http://192.168.1.100:3000
The code command requires API keys to be configured. Make sure you’ve set up your AI provider keys using nut config set-key.

​
Exiting the Session

To exit the coding session:
  • Type exit or quit
  • Press Ctrl+C (may require confirmation)
Your progress is automatically saved, and you can resume later by running nut code <task-id> again.