Overview

The Code-Executor is GemKit's workhorse implementation agent, designed for plan-driven, test-driven development. Unlike generic coding assistants, Code-Executor follows a disciplined methodology: understand the task, create a plan, implement incrementally, verify with tests, and iterate based on feedback. Whether you're building a new feature from scratch, refactoring legacy code, or fixing complex bugs, Code-Executor brings structure and reliability to AI-assisted development.

Core Philosophy:

Plan before code - Never rush into implementation without a clear strategy
Test-driven development - Write tests to validate behavior
Incremental implementation - Build step-by-step, verify each step
Self-verification - Run tests and checks before considering work complete

When to Use Code-Executor

✅ Ideal Use Cases

Feature Implementation

New API endpoints with full CRUD operations
React components with state management
Database models and migrations
Authentication and authorization systems

Refactoring Tasks

Modernizing legacy code patterns
Extracting reusable components
Improving code organization
Performance optimizations

Bug Fixes

Issues with clear reproduction steps
Regression fixes requiring tests
Type errors and lint violations
Integration problems

Code Migrations

Framework upgrades (React 17 → 19)
Library replacements (Axios → Fetch)
API version migrations
Database schema changes

❌ Not Ideal For

Open-ended Research → Use Researcher agent instead

Technology comparisons
Best practices exploration
Architecture decisions

Test-Only Tasks → Use Tester agent instead

Generating tests for existing code
Coverage analysis
Test suite improvements

Quick Experiments → Use direct AI chat

Proof of concepts
Throwaway prototypes
Learning exercises

Spawning Code-Executor

Basic Usage

bash

gk agent spawn --agent code-executor \
  --prompt "Implement a user authentication service with JWT tokens"

What happens:

Agent analyzes the prompt and breaks down requirements
Creates an implementation plan with phases
Implements code following plan steps
Writes tests to verify functionality
Runs tests and reports results
Provides summary of changes

With Skills

Skills inject domain-specific knowledge and patterns into the agent's context.

bash

# Frontend implementation
gk agent spawn --agent code-executor \
  --skills "frontend-development" \
  --prompt "Create a responsive navigation bar with mobile menu"

# Backend implementation
gk agent spawn --agent code-executor \
  --skills "backend-development" \
  --prompt "Add OAuth 2.1 login flow with refresh tokens"

# Full-stack with multiple skills
gk agent spawn --agent code-executor \
  --skills "frontend-development,backend-development,testing" \
  --prompt "Build a real-time chat feature with WebSockets"

Available skills:

frontend-development - React 19, TanStack, MUI v7, Zustand, Vitest
backend-development - Node.js, Python, APIs, OAuth, PostgreSQL
frontend-design - UI/UX, CSS, animations
testing - Vitest, Jest, Playwright, MSW

With Context

Provide relevant files to guide implementation and ensure consistency.

bash

# Single file context
gk agent spawn --agent code-executor \
  --context src/services/auth.ts \
  --prompt "Add password reset functionality to the auth service"

# Multiple files
gk agent spawn --agent code-executor \
  --context src/types/user.ts,src/services/auth.ts,src/middleware/authenticate.ts \
  --prompt "Add two-factor authentication support"

# Directory context (use sparingly - can be expensive)
gk agent spawn --agent code-executor \
  --context src/components/ \
  --prompt "Add loading states to all async components"

Context best practices:

Include only directly relevant files (reduces token usage)
Provide type definitions for better accuracy
Include related configuration files when needed
Avoid entire directories unless necessary

With Model Selection

Choose the right model based on task complexity.

bash

# Simple tasks - Fast and cheap
gk agent spawn --agent code-executor \
  --model gemini-2.0-flash \
  --prompt "Add a contact form component"

# Complex tasks - Better reasoning
gk agent spawn --agent code-executor \
  --model gemini-2.0-pro \
  --prompt "Implement distributed caching with Redis cluster"

# Critical systems - Highest quality
gk agent spawn --agent code-executor \
  --model claude-3-opus --cli claude \
  --prompt "Design fault-tolerant payment processing system"

Real-World Scenarios

Scenario 1: Implementing a React Component

Task: Create a user profile card with avatar, bio, and edit functionality.

bash

gk agent spawn --agent code-executor \
  --skills "frontend-development" \
  --context src/types/user.ts,src/components/Avatar.tsx \
  --prompt "Create a UserProfileCard component that displays user avatar, name, bio, and an edit button. Use MUI for styling and Zustand for state management. Include loading and error states."

Expected workflow:

Planning Phase (agent creates mental plan):

markdown

Plan:
1. Create UserProfileCard.tsx component structure
2. Define props interface based on User type
3. Implement layout with MUI components
4. Add Zustand store for edit state
5. Handle loading/error states
6. Write Vitest unit tests

Implementation:
- Creates src/components/UserProfileCard.tsx
- Imports User type from existing src/types/user.ts
- Uses existing Avatar component
- Implements responsive design with MUI Grid
- Adds state management with Zustand
Testing:
- Creates src/components/UserProfileCard.test.tsx
- Tests rendering with mock data
- Tests loading state
- Tests error handling
- Tests edit button interaction
Verification:
- Runs tests: npm run test UserProfileCard
- Reports results: "✓ All 5 tests passed"

Output files:

src/components/UserProfileCard.tsx (142 lines)
src/components/UserProfileCard.test.tsx (78 lines)
src/stores/profileStore.ts (optional, if needed)

Scenario 2: Adding an API Endpoint

Task: Create a REST API endpoint for user settings management.

bash

gk agent spawn --agent code-executor \
  --skills "backend-development,testing" \
  --context src/types/user.ts,src/middleware/authenticate.ts,src/routes/index.ts \
  --prompt "Add CRUD endpoints for user settings at /api/settings. Settings should include theme, notifications, and privacy preferences. Require authentication. Include input validation and comprehensive tests."

Expected workflow:

Planning Phase:

markdown

Plan:
1. Define UserSettings type and database model
2. Create settings controller with CRUD methods
3. Add validation schemas with Zod
4. Implement routes with authentication middleware
5. Write integration tests

Implementation:
- src/types/settings.ts - TypeScript interfaces
- src/models/UserSettings.ts - Database model
- src/controllers/settingsController.ts - Business logic
- src/validators/settings.ts - Zod schemas
- src/routes/settings.ts - Express routes
- Updates src/routes/index.ts to register routes
Testing:
- tests/integration/settings.test.ts - Full E2E tests
- Tests all CRUD operations
- Tests authentication requirements
- Tests validation errors
- Tests edge cases
Verification:
- Runs integration tests
- Tests actual HTTP requests
- Verifies database operations

Output summary:

markdown

✓ Created 6 files
✓ Modified 1 file
✓ Added 342 lines of code
✓ All 18 tests passing
✓ Coverage: 94%

Scenario 3: Refactoring Legacy Code

Task: Modernize class-based React components to functional components with hooks.

bash

gk agent spawn --agent code-executor \
  --skills "frontend-development" \
  --context src/components/Dashboard.jsx,src/components/DataTable.jsx \
  --prompt "Refactor these class components to functional components using React 19 hooks. Replace componentDidMount with useEffect, convert state to useState, and use TypeScript. Maintain existing functionality exactly and add tests."

Expected workflow:

Planning Phase:

markdown

Plan:
1. Analyze existing component structure and lifecycle methods
2. Map class methods to hook equivalents
3. Convert to TypeScript with proper types
4. Refactor one component at a time
5. Verify behavior matches original
6. Add tests to prevent regression

Implementation:
- Converts Dashboard.jsx → Dashboard.tsx
- Replaces this.state with useState
- Replaces lifecycle methods with useEffect
- Adds TypeScript types
- Preserves all existing functionality
Testing:
- Creates comprehensive tests for refactored components
- Tests match original behavior
- Adds regression tests
Verification:
- Compares old vs. new behavior
- Ensures no breaking changes

Before (Dashboard.jsx):

jsx

class Dashboard extends React.Component {
  constructor(props) {
    super(props);
    this.state = { data: null, loading: true };
  }

  componentDidMount() {
    fetchData().then(data => {
      this.setState({ data, loading: false });
    });
  }

  render() {
    const { data, loading } = this.state;
    // ...
  }
}

After (Dashboard.tsx):

tsx

import { useState, useEffect } from 'react';

interface DashboardProps {
  // ...
}

export const Dashboard: React.FC<DashboardProps> = (props) => {
  const [data, setData] = useState<Data | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    fetchData().then(data => {
      setData(data);
      setLoading(false);
    });
  }, []);

  // ...
};

Scenario 4: Fixing a Bug with Tests

Task: Fix authentication bug where tokens expire but UI doesn't reflect it.

bash

gk agent spawn --agent code-executor \
  --skills "backend-development,frontend-development" \
  --context src/services/auth.ts,src/hooks/useAuth.ts,src/middleware/authenticate.ts \
  --prompt "Fix bug: When JWT token expires, API returns 401 but frontend doesn't redirect to login. Add proper token expiry checking, auto-refresh logic, and update UI state. Include tests for token expiration scenarios."

Expected workflow:

Planning Phase:

markdown

Plan:
1. Identify token expiry check gap
2. Add token refresh mechanism
3. Update frontend auth state management
4. Add API interceptor for 401 responses
5. Implement automatic redirect
6. Write tests for expiry scenarios

Implementation:
- Fixes token validation in src/middleware/authenticate.ts
- Adds refresh token logic to src/services/auth.ts
- Updates src/hooks/useAuth.ts to handle expiry
- Adds Axios interceptor for 401 responses
- Implements auto-redirect to login
Testing:
- Tests token expiry detection
- Tests refresh token flow
- Tests 401 response handling
- Tests redirect behavior
- Tests edge cases (network failure during refresh)
Verification:
- Runs all auth tests
- Manually tests expiry scenario
- Confirms bug is fixed

Scenario 5: Building a Feature End-to-End

Task: Complete user registration with email verification.

bash

gk agent spawn --agent code-executor \
  --skills "frontend-development,backend-development,testing" \
  --prompt "Implement complete user registration flow: signup form, email verification with expiring tokens, resend verification email, and auto-login after verification. Include frontend components, API endpoints, email service integration, and comprehensive tests."

Expected workflow:

Planning Phase (detailed multi-step plan):

markdown

Phase 1: Backend
- Create User model with verification fields
- Add registration endpoint
- Implement email verification token generation
- Create verify-email endpoint
- Add resend-verification endpoint

Phase 2: Frontend
- Create SignupForm component
- Create EmailVerification component
- Add email verification UI flow

Phase 3: Testing
- Unit tests for backend logic
- Integration tests for API endpoints
- Component tests for frontend
- E2E test for complete flow

Implementation (creates 12+ files):
- Backend: models, controllers, services, routes
- Frontend: components, hooks, API clients
- Email: templates, service integration
- Config: environment variables
Testing (comprehensive test suite):
- Backend unit tests (token generation, validation)
- API integration tests (registration, verification)
- Frontend component tests
- E2E test (complete user journey)
Verification:
- Runs full test suite
- Reports coverage
- Lists all created/modified files

Output:

markdown

✓ Feature implementation complete
✓ Created 14 files, modified 3 files
✓ Added 1,248 lines of code
✓ All 42 tests passing
✓ Coverage: 91%

Files created:
Backend:
- src/models/User.ts
- src/controllers/authController.ts
- src/services/emailService.ts
- src/services/verificationService.ts
- src/routes/auth.ts
- src/validators/auth.ts

Frontend:
- src/components/SignupForm.tsx
- src/components/EmailVerification.tsx
- src/hooks/useAuth.ts
- src/api/authClient.ts

Tests:
- tests/unit/verification.test.ts
- tests/integration/auth.test.ts
- tests/components/SignupForm.test.tsx
- tests/e2e/registration.spec.ts

The /code Workflow Integration

The Code-Executor is the core agent in the /code workflow, which orchestrates a complete development cycle:

bash

# Using the /code workflow
gk agent spawn --agent code-executor \
  --workflow code \
  --prompt "Build a user dashboard feature"

Workflow phases:

Research (Researcher agent spawned)
- Investigates best practices
- Identifies patterns and libraries
- Documents recommendations
Planning (Code-Executor in plan mode)
- Reviews research findings
- Creates implementation plan
- Defines acceptance criteria
Implementation (Code-Executor)
- Executes plan step-by-step
- Writes production code
- Maintains consistency
Verification (Tester agent spawned)
- Generates comprehensive tests
- Runs test suite
- Reports coverage

When to use /code workflow vs. direct Code-Executor:

Use /code: For complete features requiring research and testing
Use Code-Executor directly: When you already know the approach and just need implementation

Best Practices

1. Provide Clear Acceptance Criteria

bash

# ❌ Vague
gk agent spawn --agent code-executor --prompt "Add user feature"

# ✅ Clear
gk agent spawn --agent code-executor --prompt "Add user profile editing with:
- Form validation (email format, required fields)
- Optimistic UI updates
- Error handling with user-friendly messages
- Save button disabled during submission
- Success notification on save"

2. Include Relevant Context

bash

# ❌ No context
gk agent spawn --agent code-executor --prompt "Fix the auth bug"

# ✅ With context
gk agent spawn --agent code-executor \
  --context src/services/auth.ts,src/types/user.ts \
  --prompt "Fix auth bug: tokens not refreshing on expiry"

3. Let the Agent Plan First

Don't micromanage—trust the planning process:

bash

# ❌ Over-specified steps
gk agent spawn --agent code-executor --prompt "
Step 1: Create file A
Step 2: Add function B
Step 3: Import C
..."

# ✅ Outcome-focused
gk agent spawn --agent code-executor --prompt "
Implement user authentication with JWT tokens.
Requirements:
- Secure password hashing
- Token expiration and refresh
- Protected route middleware
Include tests."

4. Review Before Accepting Changes

Always review generated code:

bash

# After agent completes
gk session view <session-id>

# Review changes
git diff

# Run tests yourself
npm test

# Accept if satisfied, or iterate
gk agent spawn --agent code-executor --prompt "Update the implementation to..."

5. Use Appropriate Models

bash

# Simple CRUD → Flash (fast, cheap)
gk agent spawn --agent code-executor --model gemini-2.0-flash \
  --prompt "Add contact form"

# Complex logic → Pro (better reasoning)
gk agent spawn --agent code-executor --model gemini-2.0-pro \
  --prompt "Implement state machine for order workflow"

# Critical systems → Opus (highest quality)
gk agent spawn --agent code-executor --model claude-3-opus --cli claude \
  --prompt "Design financial transaction system with rollback"

6. Iterate Based on Feedback

bash

# Initial implementation
gk agent spawn --agent code-executor --prompt "Add user search"

# After review, refine
gk agent spawn --agent code-executor \
  --context src/components/UserSearch.tsx \
  --prompt "Add debouncing to search input and improve error handling"

Customizing the Agent

You can modify the Code-Executor agent definition to match your team's needs:

File: .gemini/agents/code-executor/agent.md

markdown

---
name: code-executor
description: Plan-driven, test-driven code implementation
model: gemini-2.0-flash
---

# Role

You are a code implementation specialist...

# Additional Team Guidelines

## Code Style
- Use semicolons in TypeScript
- Prefer named exports over default exports
- Maximum function length: 50 lines

## Testing Requirements
- Minimum 85% coverage
- Test happy path and error cases
- Use descriptive test names

## Commit Messages
- Format: type(scope): description
- Types: feat, fix, refactor, test

Activate customized agent:

bash

gk agent spawn --agent code-executor --prompt "..."
# Automatically uses your customized version

Troubleshooting

Agent Makes Incorrect Assumptions

Problem: Generated code doesn't match expected architecture.

Solution:

bash

# Add more context files
gk agent spawn --agent code-executor \
  --context src/architecture.md,src/types/,src/config/ \
  --prompt "..."

# Or be more explicit in prompt
gk agent spawn --agent code-executor --prompt "
Using our existing service layer pattern (see src/services/base.ts),
implement..."

Implementation Differs from Expectation

Problem: Code works but uses different approach than you wanted.

Solution:

bash

# Refine prompt with specific approach
gk agent spawn --agent code-executor --prompt "
Implement user caching using Redis (not in-memory).
Follow the pattern in src/cache/productCache.ts.
Use TTL of 1 hour."

Tests Fail After Implementation

Problem: Agent completes but tests don't pass.

Solution:

bash

# Let agent iterate (it expects to iterate)
gk agent spawn --agent code-executor \
  --context src/components/Widget.tsx,tests/Widget.test.tsx \
  --prompt "Fix the failing tests in Widget.test.tsx. The issue is..."

# Or spawn Tester agent
gk agent spawn --agent tester \
  --context src/components/Widget.tsx \
  --prompt "Analyze failing tests and fix them"

Agent Tries to Modify Too Many Files

Problem: Agent wants to refactor unrelated code.

Solution:

bash

# Be explicit about scope
gk agent spawn --agent code-executor --prompt "
Add password reset functionality to auth service.
ONLY modify src/services/auth.ts and add tests.
DO NOT refactor existing authentication logic."

Tester Agent Guide - Comprehensive testing
Researcher Agent - Pre-implementation research
Multi-Agent Orchestration - Coordinating agents
Skills Reference - Available skills
Workflows - Understanding /code and custom workflows
Creating Custom Agents - Customization guide

Summary

The Code-Executor agent is your reliable implementation partner, bringing structure and discipline to AI-assisted development. By following a plan-driven, test-driven methodology, it ensures quality and maintainability while significantly accelerating development velocity. Use it for feature implementation, refactoring, bug fixes, and migrations—any task where structured, verified code generation is needed.

Key takeaways:

Always provide clear requirements and acceptance criteria
Include relevant context files for better accuracy
Trust the planning process—don't micromanage
Review generated code before accepting
Use appropriate models based on complexity
Customize agent definition for team standards
Iterate based on feedback and results

Overview

When to Use Code-Executor

✅ Ideal Use Cases

❌ Not Ideal For

Spawning Code-Executor

Basic Usage

With Skills

With Context

With Model Selection

Real-World Scenarios

Scenario 1: Implementing a React Component

Scenario 2: Adding an API Endpoint

Scenario 3: Refactoring Legacy Code

Scenario 4: Fixing a Bug with Tests

Scenario 5: Building a Feature End-to-End

The /code Workflow Integration

Best Practices

1. Provide Clear Acceptance Criteria

2. Include Relevant Context

3. Let the Agent Plan First

4. Review Before Accepting Changes

5. Use Appropriate Models

6. Iterate Based on Feedback

Customizing the Agent

Troubleshooting

Agent Makes Incorrect Assumptions

Implementation Differs from Expectation

Tests Fail After Implementation

Agent Tries to Modify Too Many Files

Related Documentation

Summary