Full Self Coding (FSC)

Multi-node clustering is optional (Redis Streams). Third-party gateways such as OpenClaw are optional integrations, not requirements: see docs/deployment/openclaw-mesh.md.

原版: https://github.com/NO-CHATBOT-REVOLUTION/full-self-coding

Run many AI coding agents in parallel on one codebase, each in an isolated worktree, with scope contracts to keep their changes from colliding.

Scale: defaults to 5 concurrent agents; merging is serial. With mock agents on one machine, 1000 independent tasks ran to completion in 7.7 minutes, and orchestration should not limit you below roughly 200 simultaneous agents. Real-agent memory, model rate limits and cost, and large repositories are not measured. Details and caveats: docs/reports/scale-bench.md (issue #10).

🌟 Overview

Status: the TypeScript implementation in packages/ is the current release. The core is being rewritten as a pure-Rust single binary (crates/, tracked in #2); fsc-scope (scope contracts, drift scoring, co-change coupling) is done and is checked against the TypeScript reference with golden tests. Module boundaries and import rules: MODULE_STRUCTURE.md.

Full Self Coding (FSC) is a sophisticated framework designed to automate software engineering tasks by running multiple AI coding agents (Claude Code, Gemini CLI, Codex, Cursor, and others) in parallel, each in an isolated git worktree or Docker container. It provides intelligent codebase analysis, task decomposition, automated code modification, and comprehensive reporting capabilities.

Key Features

🤖 Multi-Agent Support: Integration with Claude Code, Gemini CLI, and extensible agent architecture
📦 Containerized Execution: Secure, isolated Docker-based task execution
🔍 Intelligent Analysis: Automated codebase analysis and task identification
⚙️ Flexible Configuration: Hierarchical configuration system with environment variable support
📊 Comprehensive Reporting: Detailed execution reports with git diff tracking
🔄 Parallel Processing: Multi-container parallel task execution with resource management
🛡️ Robust Error Handling: Comprehensive error recovery and graceful degradation

Deployment shapes

Shape	Needs	How
Single machine	Bun, git (Docker optional)	`executionMode: "bare"` (git worktree) or Docker
Multi-node	Redis	`DistributedScheduler` over Redis Streams; set `FSC_REDIS_URL`
Mesh with a gateway (optional)	OpenClaw, WireGuard	see docs/deployment/openclaw-mesh.md

Supported Agent Types

Agent Type	Description	Container Image	Key Features
CLAUDE_CODE	Anthropic Claude Code integration	`node:latest`	Advanced code analysis, natural language processing
GEMINI_CLI	Google Gemini CLI integration	`node:latest`	Google's AI model integration, fast response
CODEX	OpenAI Codex integration (planned)	-	OpenAI GPT-based code completion

Execution Modes

FSC runs agents as native processes by default. Docker is an optional isolation mode, not a requirement.

Mode	Isolation	Overhead	Best For
worktree (default)	One native git worktree per task, agent runs as a normal process	~0	Everyday use, many parallel agents
bare	Fresh git clone + spawned process	disk only	When worktrees are not suitable
docker (optional)	Full container isolation	~200MB/agent	Untrusted code

Select with --mode, the FSC_EXECUTION_MODE environment variable, or .fsc/config.json:

{
  "executionMode": "worktree"
}

Agent Daemon

The Agent Daemon is a long-running process that replaces the old per-task worker model. It manages a pool of agents, handles heartbeats, and exposes a local HTTP API.

Agent Daemon (port 18791)
├── Agent Pool (pre-warmed agents, auto-scaling)
├── Heartbeat + Resource Reporting
├── Bubblewrap Sandbox (lightweight alternative to Docker)
└── HTTP API (health, status, task submission)

Environment Variables:

Variable	Default	Description
`AGENT_ID`	auto	Unique agent identifier
`MAX_AGENTS`	`10`	Maximum agents in pool
`MIN_AGENTS`	`2`	Minimum pre-warmed agents
`REDIS_URL`	`redis://127.0.0.1:6379`	Redis connection for distributed scheduling
`WORKSPACE`	`.`	Working directory
`SANDBOX`	`bubblewrap`	Sandbox backend (`bubblewrap` or `docker`)
`API_PORT`	`18791`	Local management API port

Agent Pool

Agents are expensive to create and destroy. The Agent Pool pre-warms N agents and reuses them across tasks — similar to how CUDA Streaming Multiprocessors reuse warps.

Auto-scaling: Scales between MIN_AGENTS and MAX_AGENTS based on queue depth
Health checks: 30s interval, auto-recycles unhealthy agents
Expiry: Idle agents are reclaimed after configurable TTL

Distributed Scheduler (Redis Streams)

For multi-node deployments, the DistributedScheduler uses Redis Streams for reliable task distribution:

Task Submit → Redis Stream (fsc:tasks) → Consumer Group → Node pulls → Execute → ACK

Supports multiple consumer groups (one per node)
At-least-once delivery with automatic retry on failure
JSON task payloads with priority ordering

Quality Gate & Trust Hooks

The CodeCommitter integrates governance hooks for automated quality control:

QualityGateHook: Evaluates commits before merge → APPROVE / REVIEW / REJECT
TrustUpdateHook: Updates agent trust score after task completion (feeds back into scheduling priority)

const committer = new CodeCommitter({
  qualityGate: async (diff) => ({ decision: 'APPROVE', score: 0.95 }),
  trustUpdate: async (agentId, result) => { /* update trust factor */ }
});

Cluster Health Check

Built-in health monitoring for multi-node deployments:

Node connectivity (WireGuard + SSH fallback)
Redis reachability
Agent pool utilization per node
Automatic alerting on node failures

🚀 Getting Started

Prerequisites

Bun (v1.0.0 or higher)
Git (for repository operations and the default worktree execution mode)
Docker (optional: only for executionMode: "docker")
Redis (optional: only for multi-node scheduling)
Rust stable (optional: only to build or test the crates/ workspace)

Quick Start

Install bun.js on your machine

curl -fsSL https://bun.sh/install | bash

Clone and setup the project

git clone https://github.com/NO-CHATBOT-REVOLUTION/full-self-coding.git
cd full-self-coding
bun install

Run on a repository

# Run CLI from source
bun run start

# Or run on a specific repository
full-self-coding

Installation as npm Package

The project is structured as a monorepo with two main packages:

@full-self-coding/core: Core library for code analysis and task execution
@full-self-coding/cli: Command-line interface

Core Package

npm install @full-self-coding/core

CLI Package

npm install -g @full-self-coding/cli
# Then run:
full-self-coding-cli

⚙️ Configuration

Configuration Hierarchy

Full Self Coding uses a hierarchical configuration system with the following precedence (highest to lowest):

Environment Variables (FSC_*)
Project-level Configuration (.fsc/config.json)
User Configuration (~/.config/full-self-coding/config.json)
Default Values

Configuration Options

Field	Type	Default	Description
`agentType`	`SWEAgentType`	`CLAUDE_CODE`	AI agent to use (`claude-code`, `gemini-cli`)
`maxDockerContainers`	`number`	`10`	Maximum Docker containers allowed
`maxParallelDockerContainers`	`number`	`3`	Maximum parallel container execution
`dockerTimeoutSeconds`	`number`	`600`	Docker command timeout in seconds
`dockerMemoryMB`	`number`	`1024`	Docker container memory limit in MB
`dockerCpuCores`	`number`	`2`	Docker container CPU core limit
`dockerImageRef`	`string`	`"node:latest"`	Docker image reference for containers
`maxTasks`	`number`	`100`	Maximum tasks to generate during analysis
`minTasks`	`number`	`1`	Minimum tasks to generate during analysis
`workStyle`	`WorkStyle`	`DEFAULT`	Work style (`default`, `bold_genius`, `careful`, etc.)
`customizedWorkStyle`	`string`	-	Custom work style description
`codingStyleLevel`	`number`	`5`	Coding style level (0-10)
`customizedCodingStyle`	`string`	-	Custom coding style description
`anthropicAPIKey`	`string`	-	Anthropic API key
`anthropicAPIBaseUrl`	`string`	-	Custom Anthropic API base URL
`anthropicAPIKeyExportNeeded`	`boolean`	`true`	Whether to export Anthropic API key
`googleGeminiApiKey`	`string`	-	Google Gemini API key
`googleGeminiAPIKeyExportNeeded`	`boolean`	`true`	Whether to export Gemini API key
`openAICodexApiKey`	`string`	-	OpenAI Codex API key
`openAICodexAPIKeyExportNeeded`	`boolean`	`true`	Whether to export OpenAI API key

Configuration Files

Global Configuration (`~/.config/full-self-coding/config.json`)

{
  "agentType": "claude-code",
  "anthropicAPIKey": "sk-ant-api03-...",
  "maxDockerContainers": 8,
  "maxParallelDockerContainers": 4,
  "dockerTimeoutSeconds": 600,
  "dockerMemoryMB": 2048,
  "workStyle": "bold_genius",
  "customizedWorkStyle": "Focus on rapid prototyping and innovation"
}

Project Configuration (`.fsc/config.json`)

{
  "agentType": "gemini-cli",
  "googleGeminiApiKey": "AIzaSy...",
  "maxTasks": 50,
  "minTasks": 5,
  "codingStyleLevel": 8,
  "customizedCodingStyle": "Follow enterprise coding standards with comprehensive documentation"
}

Environment Variables

# API Keys
export FSC_ANTHROPIC_API_KEY="sk-ant-api03-..."
export FSC_GOOGLE_GEMINI_API_KEY="AIzaSy..."
export FSC_OPENAI_CODEX_API_KEY="sk-..."

# Docker Settings
export FSC_MAX_DOCKER_CONTAINERS=15
export FSC_DOCKER_TIMEOUT_SECONDS=900
export FSC_DOCKER_MEMORY_MB=4096

# Agent Configuration
export FSC_AGENT_TYPE="claude-code"
export FSC_WORK_STYLE="bold_genius"
export FSC_CODING_STYLE_LEVEL=9

📖 Usage Guide

Command Line Interface

The CLI provides various options for configuration and execution:

full-self-coding-cli run [options]

Options

Option	Short	Type	Description
`--agent-type`	`-a`	`string`	AI agent type (`claude-code`, `gemini-cli`)
`--config`	`-c`	`string`	Path to configuration file
`--help`	`-h`	-	Show help information
`--version`	`-V`	-	Show version information

Examples

Basic Repository Analysis

# Analyze current repository with default settings
full-self-coding-cli run

# Analyze with custom config
full-self-coding-cli run --config ./my-config.json

Core Library Usage

import { analyzeCodebase, TaskSolverManager, createConfig } from '@full-self-coding/core';

// Create configuration
const config = createConfig({
  agentType: 'claude-code',
  anthropicAPIKey: 'your-api-key'
});

// Analyze repository
const tasks = await analyzeCodebase(config, 'https://github.com/user/repo.git');

// Execute tasks
const taskSolver = new TaskSolverManager(config, 'https://github.com/user/repo.git');
for (const task of tasks) {
  taskSolver.addTask(task);
}
await taskSolver.start();

🔧 API Reference

Core Classes

ConfigReader

Manages configuration loading, validation, and merging.

import { ConfigReader, readConfigWithEnv } from '@full-self-coding/core';

// Read configuration with environment variable support
const config = readConfigWithEnv();

// Create custom configuration
import { createConfig } from '@full-self-coding/core';
const customConfig = createConfig({
  agentType: 'claude-code',
  anthropicAPIKey: 'your-api-key'
});

Methods

readConfigWithEnv(): Config - Read config with environment variables
createConfig(userConfig: Partial<Config>): Config - Create configuration from user config
getGitRemoteUrls(useSSH?: boolean): Promise<{fetchUrl: string, pushUrl: string}> - Get git remote URLs

DockerInstance

Manages Docker container lifecycle and operations.

import { DockerInstance, DockerRunStatus } from '@full-self-coding/core';

const docker = new DockerInstance();

// Start container
const containerName = await docker.startContainer('node:latest', 'my-task');

// Run commands
const result = await docker.runCommands(['npm', 'install']);

// Copy files
await docker.copyFileToContainer('local.txt', '/app/remote.txt');
await docker.copyFilesToContainer('./src', '/app/src');

// Copy files from container
const content = await docker.copyFileFromContainer('/app/output.txt');

// Shutdown
await docker.shutdownContainer();

Methods

startContainer(imageRef: string, taskName?: string): Promise<string> - Start new container
runCommands(commands: string[], timeout?: number): Promise<DockerRunResult> - Execute commands
copyFileToContainer(localPath: string, containerPath: string): Promise<void> - Copy single file
copyFilesToContainer(localPath: string, containerPath: string): Promise<void> - Copy recursively
copyFileFromContainer(containerPath: string): Promise<string> - Copy file from container
shutdownContainer(): Promise<void> - Stop and remove container

TaskSolver

Executes individual tasks within Docker containers.

import { TaskSolver, SWEAgentType } from '@full-self-coding/core';

const taskSolver = new TaskSolver(
  config,
  task,
  SWEAgentType.CLAUDE_CODE,
  'https://github.com/user/repo.git'
);

// Solve the task
await taskSolver.solve();

// Get results
const result = taskSolver.getResult();

Methods

solve(shutdown?: boolean): Promise<void> - Execute the task
getResult(): TaskResult - Get task execution result

Analyzer

Analyzes codebases and generates task lists.

import { analyzeCodebase } from '@full-self-coding/core';

// Analyze a repository
const tasks = await analyzeCodebase(
  config,
  'https://github.com/user/repo.git'
);

Configuration Types

interface Config {
  agentType: SWEAgentType;
  maxDockerContainers: number;
  maxParallelDockerContainers: number;
  dockerTimeoutSeconds: number;
  dockerMemoryMB: number;
  dockerCpuCores: number;
  dockerImageRef: string;
  maxTasks: number;
  minTasks: number;
  workStyle: WorkStyle;
  customizedWorkStyle?: string;
  codingStyleLevel: number;
  customizedCodingStyle?: string;
  anthropicAPIKey?: string;
  anthropicAPIBaseUrl?: string;
  anthropicAPIKeyExportNeeded: boolean;
  googleGeminiApiKey?: string;
  googleGeminiAPIKeyExportNeeded: boolean;
  openAICodexApiKey?: string;
  openAICodexAPIKeyExportNeeded: boolean;
}

enum SWEAgentType {
  CLAUDE_CODE = 'claude-code',
  GEMINI_CLI = 'gemini-cli',
  CODEX = 'codex'
}

enum WorkStyle {
  DEFAULT = 'default',
  BOLDGENIUS = 'bold_genius',
  CAREFUL = 'careful',
  AGILE = 'agile',
  RESEARCH = 'research'
}

🧪 Testing

Running Tests

# Run all tests from project root
bun run test

# Or run from core package
cd packages/core
bun test

# Run with timeout
bun test --timeout 30000

Test Structure

packages/core/test/
├── dockerInstance.test.ts           # Docker functionality tests
├── configReaderSupplementary.test.ts # Configuration system tests
├── taskSolverClaudeCode.test.ts     # Claude Code task solver tests
├── taskSolverGemini.test.ts         # Gemini task solver tests
└── integration/                     # Integration tests
    ├── full-workflow.test.ts        # End-to-end workflow tests
    └── multi-agent.test.ts          # Multi-agent integration tests

Writing Tests

import { expect, test, describe, beforeAll, afterAll } from 'bun:test';
import { DockerInstance } from '@full-self-coding/core';

describe('DockerInstance', () => {
  let docker: DockerInstance;
  let containerName: string;

  beforeAll(async () => {
    docker = new DockerInstance();
    containerName = await docker.startContainer('node:latest', 'test-container');
  });

  afterAll(async () => {
    await docker.shutdownContainer();
  });

  test('should run simple commands', async () => {
    const result = await docker.runCommands(['echo', 'hello']);
    expect(result.status).toBe(DockerRunStatus.SUCCESS);
    expect(result.output).toContain('hello');
  });
});

🐳 Docker Integration

Container Management

FSC creates isolated Docker containers for each task execution, ensuring:

Security: Complete isolation from host system
Consistency: Reproducible execution environments
Parallelism: Multiple tasks can run simultaneously
Resource Management: Controlled CPU and memory usage

Supported Operations

File copying (both directions)
Command execution with timeout protection
Real-time output streaming
Resource monitoring
Graceful shutdown

Custom Docker Images

You can use custom Docker images:

{
  "dockerImageRef": "custom/node:18-alpine",
  "dockerMemoryMB": 1536,
  "dockerCpuCores": 3
}

🔍 Troubleshooting

Common Issues

Docker Connectivity

# Check Docker daemon
docker --version
docker info

# Test container creation
docker run --rm hello-world

Permission Issues

# Add user to docker group (Linux)
sudo usermod -aG docker $USER
newgrp docker

API Key Problems

# Verify API key format
echo $FSC_ANTHROPIC_API_KEY | head -c 20

# Test API connectivity
curl -H "x-api-key: $FSC_ANTHROPIC_API_KEY" \
     https://api.anthropic.com/v1/messages \
     -d '{"model":"claude-3-sonnet-20240229","max_tokens":10,"messages":[{"role":"user","content":"Hi"}]}'

Debug Mode

Enable debug logging:

export DEBUG=fsc:*
node dist/main.js --debug https://github.com/user/repo.git

Performance Tuning

Resource Optimization

{
  "maxParallelDockerContainers": 2,
  "dockerTimeoutSeconds": 900,
  "dockerMemoryMB": 2048
}

Task Limiting

{
  "maxTasks": 50,
  "minTasks": 5
}

🤝 Contributing

Development Setup

Fork and clone

git clone https://github.com/NO-CHATBOT-REVOLUTION/full-self-coding.git
cd full-self-coding

Install development dependencies
```
bun install
```

Code Style

TypeScript: Strict mode enabled
Pure TypeScript: No build step required
Bun: Fast JavaScript runtime

# Run tests
bun run test

# Run development server
bun run dev

# Start CLI
bun run start

Testing Requirements

Coverage: Minimum 90% coverage required
Unit Tests: All public methods must have tests
Integration Tests: Critical workflows must be tested

# Run tests
bun run test

# Run tests with timeout
bun run test --timeout 30000

Pull Request Process

Create feature branch
```
git checkout -b feature/new-feature
```
Make changes and test
```
bun run test
```

Commit and push

git commit -m "feat: add new feature"
git push origin feature/new-feature

Create pull request
- Include comprehensive description
- Reference related issues
- Include test results

📚 Advanced Topics

Custom Agent Integration

To add a new agent type:

Define enum value

// src/config.ts
export enum SWEAgentType {
  CLAUDE_CODE = 'claude-code',
  GEMINI_CLI = 'gemini-cli',
  CODEX = 'codex',
  CUSTOM_AGENT = 'custom-agent'
}

Implement agent commands

// src/SWEAgent/customAgentCommands.ts
export function customAgentCommands(
  config: Config,
  task: Task,
  gitUrl: string
): string[] {
  // Implementation
}

Update command builder

// src/SWEAgent/SWEAgentTaskSolverCommands.ts
switch (agentType) {
  case SWEAgentType.CUSTOM_AGENT:
    return customAgentCommands(config, task, gitUrl);
}

Custom Work Styles

Define custom work styles by extending the WorkStyle enum and implementing corresponding prompt generation logic.

Monitoring and Observability

Metrics Collection

FSC supports integration with monitoring systems:

// Add custom metrics
import { MetricsCollector } from './src/metrics';

const metrics = new MetricsCollector();
metrics.recordTaskExecution(task, duration, success);
metrics.recordResourceUsage(containerId, cpu, memory);

Logging

Configure logging levels and outputs:

import { Logger } from './src/logger';

const logger = new Logger({
  level: 'debug',
  output: 'file',
  filename: 'fsc.log'
});

Security Considerations

API Key Management: Use environment variables or secure vault
Container Isolation: Containers run with limited privileges
Network Access: Control container network access
File System: Limit file system access within containers

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

🙏 Acknowledgments

Anthropic - For Claude Code integration
Google - For Gemini CLI integration
Docker - For containerization platform
Bun - For fast JavaScript runtime

📞 Support

GitHub Issues: Report bugs and request features
Discussions: Community discussions and Q&A
Documentation: Full documentation site (Coming Soon)

Built with ❤️ by the Full Self Coding team

Name		Name	Last commit message	Last commit date
.github		.github
.planning		.planning
crates		crates
docs		docs
examples		examples
packages		packages
script		script
.gitattributes		.gitattributes
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
MODULE_STRUCTURE.md		MODULE_STRUCTURE.md
PROJECT_INDEX.json		PROJECT_INDEX.json
README.md		README.md
bun.lockb		bun.lockb
package.json		package.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

Full Self Coding (FSC)

🌟 Overview

Key Features

Deployment shapes

Supported Agent Types

Execution Modes

Agent Daemon

Agent Pool

Distributed Scheduler (Redis Streams)

Quality Gate & Trust Hooks

Cluster Health Check

🚀 Getting Started

Prerequisites

Quick Start

Installation as npm Package

Core Package

CLI Package

⚙️ Configuration

Configuration Hierarchy

Configuration Options

Configuration Files

Global Configuration (~/.config/full-self-coding/config.json)

Project Configuration (.fsc/config.json)

Environment Variables

📖 Usage Guide

Command Line Interface

Options

Examples

Basic Repository Analysis

Core Library Usage

🔧 API Reference

Core Classes

ConfigReader

DockerInstance

TaskSolver

Analyzer

Configuration Types

🧪 Testing

Running Tests

Test Structure

Writing Tests

🐳 Docker Integration

Container Management

Supported Operations

Custom Docker Images

🔍 Troubleshooting

Common Issues

Docker Connectivity

Permission Issues

API Key Problems

Debug Mode

Performance Tuning

Resource Optimization

Task Limiting

🤝 Contributing

Development Setup

Code Style

Testing Requirements

Pull Request Process

📚 Advanced Topics

Custom Agent Integration

Custom Work Styles

Monitoring and Observability

Metrics Collection

Logging

Security Considerations

📄 License

🙏 Acknowledgments

📞 Support

About

Resources

Stars

Watchers

Forks

Releases

Packages

Global Configuration (`~/.config/full-self-coding/config.json`)

Project Configuration (`.fsc/config.json`)