refactor: use .opencode/opencoder/ directory structure

Move all opencoder files under .opencode/opencoder/ to keep all
OpenCode-related files together in a shared parent directory.

Changes:
- .opencoder/ → .opencode/opencoder/
- opencoder.json → .opencode/opencoder/config.json
- Updated fs.ts paths, config.ts loader, CLI help text
- Updated .gitignore to ignore state/logs but allow config
- Updated README.md and AGENTS.md documentation
- Renamed opencoder.json.example → config.json.example

Signed-off-by: leocavalcante <[email protected]>

Author: leocavalcante

.gitignore

@@ -1,5 +1,9 @@
-# OpenCoder
-.opencoder/
+# OpenCoder state and logs (config.json is user-managed)
+.opencode/opencoder/state.json
+.opencode/opencoder/current_plan.md
+.opencode/opencoder/logs/
+.opencode/opencoder/history/
+.opencode/opencoder/alerts.log
 
 # Bun
 node_modules/

AGENTS.md

@@ -251,7 +251,7 @@ describe("module", () => {
 ### Config Priority (lowest to highest)
 
 1. Defaults (hardcoded)
-2. `opencoder.json` in project directory
+2. `.opencode/opencoder/config.json` in project directory
 3. Environment variables (`OPENCODER_*`)
 4. CLI arguments
 
@@ -267,7 +267,7 @@ OPENCODER_LOG_RETENTION=30
 OPENCODER_TASK_PAUSE_SECONDS=2
 ```
 
-### Config File (opencoder.json)
+### Config File (.opencode/opencoder/config.json)
 
 ```json
 {
@@ -301,7 +301,7 @@ Opencoder includes an **ideas queue system** that allows users to provide specif
 
 ### How It Works
 
-1. **Ideas Directory**: `.opencoder/ideas/` - Users place `.md` files here
+1. **Ideas Directory**: `.opencode/opencoder/ideas/` - Users place `.md` files here
 2. **Plan Integration**: Before each plan cycle, the loop checks for ideas
 3. **Selection Logic**:
    - **1 idea**: Used directly (no AI selection call)
@@ -343,8 +343,8 @@ Steps:
 bun test tests/ideas.test.ts
 
 # Test full integration
-mkdir -p test-project/.opencoder/ideas
-echo "# Test idea" > test-project/.opencoder/ideas/test.md
+mkdir -p test-project/.opencode/opencoder/ideas
+echo "# Test idea" > test-project/.opencode/opencoder/ideas/test.md
 bun run dev -- -m anthropic/claude-sonnet-4 -p test-project
 ```
 
@@ -361,7 +361,7 @@ bun run dev -- -m anthropic/claude-sonnet-4 -p test-project
 2. **Build Phase**: Build tasks from the plan one by one
 3. **Evaluation Phase**: AI evaluates if cycle is complete (COMPLETE/NEEDS_WORK)
 
-State is persisted to `.opencoder/state.json` after each phase for resumability.
+State is persisted to `.opencode/opencoder/state.json` after each phase for resumability.
 
 ## CI Pipeline
 

README.md

@@ -8,7 +8,7 @@
 
 - **Autonomous Development Loop** - Continuously plans, builds, and evaluates without stopping
 - **OpenCode SDK Integration** - Direct SDK integration with real-time event streaming
-- **Ideas Queue** - Drop markdown files in `.opencoder/ideas/` to prioritize specific tasks before autonomous plan
+- **Ideas Queue** - Drop markdown files in `.opencode/opencoder/ideas/` to prioritize specific tasks before autonomous plan
 - **Two-Model Architecture** - Uses a high-capability model for plan and a faster model for building
 - **Live Output Streaming** - Real-time display of AI thinking, tool calls, and results
 - **State Persistence** - Resumes from where it left off after interruptions (JSON format)
@@ -163,9 +163,9 @@ The loop continues indefinitely until manually stopped (Ctrl+C).
 
 ## Configuration
 
-### Config File (opencoder.json)
+### Config File (.opencode/opencoder/config.json)
 
-Create an `opencoder.json` in your project directory:
+Create a `.opencode/opencoder/config.json` in your project:
 
 ```json
 {
@@ -195,27 +195,29 @@ Create an `opencoder.json` in your project directory:
 Configuration is merged in this order (later overrides earlier):
 
 1. Defaults (hardcoded)
-2. `opencoder.json` in project directory
+2. `.opencode/opencoder/config.json` in project directory
 3. Environment variables (`OPENCODER_*`)
 4. CLI arguments
 
 ## Directory Structure
 
-OpenCoder creates a `.opencoder/` directory in your project:
+OpenCoder creates a `.opencode/opencoder/` directory in your project:
 
 ```
-.opencoder/
-├── state.json               # Current state (JSON)
-├── current_plan.md          # Active task plan
-├── ideas/                   # Drop .md files here to queue tasks
-│   ├── feature-x.md
-│   └── bugfix-y.md
-├── history/                 # Archived completed plans
-│   └── plan_YYYYMMDD_HHMMSS_cycleN.md
-└── logs/
-    ├── main.log             # Main rotating log
-    └── cycles/              # Per-cycle detailed logs
-        └── cycle_001.log
+.opencode/
+└── opencoder/
+    ├── config.json              # Configuration file
+    ├── state.json               # Current state (JSON)
+    ├── current_plan.md          # Active task plan
+    ├── ideas/                   # Drop .md files here to queue tasks
+    │   ├── feature-x.md
+    │   └── bugfix-y.md
+    ├── history/                 # Archived completed plans
+    │   └── plan_YYYYMMDD_HHMMSS_cycleN.md
+    └── logs/
+        ├── main.log             # Main rotating log
+        └── cycles/              # Per-cycle detailed logs
+            └── cycle_001.log
 ```
 
 ## Plan Format
@@ -244,13 +246,13 @@ Using bcrypt for password hashing, JWT for tokens.
 
 ## Ideas Queue
 
-Want to direct OpenCoder toward specific tasks? Drop markdown files in `.opencoder/ideas/` and OpenCoder will prioritize them before generating its own plans.
+Want to direct OpenCoder toward specific tasks? Drop markdown files in `.opencode/opencoder/ideas/` and OpenCoder will prioritize them before generating its own plans.
 
 ### Quick Start
 
 ```bash
 # Create an idea
-cat > .opencoder/ideas/add-dark-mode.md << 'EOF'
+cat > .opencode/opencoder/ideas/add-dark-mode.md << 'EOF'
 # Add Dark Mode
 
 Add dark mode toggle with system preference detection.
@@ -267,7 +269,7 @@ opencoder -m anthropic/claude-sonnet-4
 
 ### How It Works
 
-1. **Before Planning** - OpenCoder checks `.opencoder/ideas/` for `.md` files
+1. **Before Planning** - OpenCoder checks `.opencode/opencoder/ideas/` for `.md` files
 2. **Smart Selection**:
    - **1 idea**: Uses it directly (no extra API call)
    - **2+ ideas**: AI evaluates all and picks the simplest/quick-win, considering dependencies
@@ -301,10 +303,10 @@ The AI prioritizes based on:
 ## Tips
 
 - **Start with a clear hint** - The more specific your instruction, the better the initial plan
-- **Use ideas for focus** - Drop task files in `.opencoder/ideas/` to direct development
+- **Use ideas for focus** - Drop task files in `.opencode/opencoder/ideas/` to direct development
 - **Let it run** - OpenCoder is designed to run continuously; trust the loop
-- **Check the logs** - Detailed logs are in `.opencoder/logs/` if something goes wrong
-- **Review history** - Completed plans are archived in `.opencoder/history/`
+- **Check the logs** - Detailed logs are in `.opencode/opencoder/logs/` if something goes wrong
+- **Review history** - Completed plans are archived in `.opencode/opencoder/history/`
 
 ## Development
 

opencoder.json.example config.json.exampleopencoder.json.example renamed to config.json.example

@@ -73,7 +73,7 @@ Environment variables:
     OPENCODER_VERBOSE           Enable verbose logging (true/1)
     OPENCODER_PROJECT_DIR       Default project directory
 
-Config file (opencoder.json):
+Config file (.opencode/opencoder/config.json):
     {
       "planModel": "anthropic/claude-sonnet-4",
       "buildModel": "anthropic/claude-sonnet-4",

src/cli.ts

@@ -3,14 +3,14 @@
  *
  * Priority (lowest to highest):
  * 1. Defaults
- * 2. opencoder.json in project directory
+ * 2. .opencode/opencoder/config.json in project directory
  * 3. Environment variables
  * 4. CLI arguments
  */
 
 import { existsSync } from "node:fs"
 import { readFile } from "node:fs/promises"
-import { resolve } from "node:path"
+import { join, resolve } from "node:path"
 import type { CliOptions, Config, ConfigFile } from "./types.ts"
 
 /** Default configuration values */
@@ -80,10 +80,10 @@ function resolveProjectDir(cliProject?: string): string {
 }
 
 /**
- * Load configuration from opencoder.json file
+ * Load configuration from .opencode/opencoder/config.json file
  */
 async function loadConfigFile(projectDir: string): Promise<Partial<Config>> {
-	const configPath = resolve(projectDir, "opencoder.json")
+	const configPath = join(resolve(projectDir), ".opencode", "opencoder", "config.json")
 
 	if (!existsSync(configPath)) {
 		return {}
@@ -103,7 +103,7 @@ async function loadConfigFile(projectDir: string): Promise<Partial<Config>> {
 			taskPauseSeconds: parsed.taskPauseSeconds,
 		}
 	} catch (err) {
-		console.warn(`Warning: Failed to parse opencoder.json: ${err}`)
+		console.warn(`Warning: Failed to parse config.json: ${err}`)
 		return {}
 	}
 }
@@ -156,13 +156,13 @@ function loadEnvConfig(): Partial<Config> {
 function validateConfig(config: Config): void {
 	if (!config.planModel) {
 		throw new Error(
-			"Missing plan model. Provide via --model, --plan-model, opencoder.json, or OPENCODER_PLAN_MODEL env var.",
+			"Missing plan model. Provide via --model, --plan-model, .opencode/opencoder/config.json, or OPENCODER_PLAN_MODEL env var.",
 		)
 	}
 
 	if (!config.buildModel) {
 		throw new Error(
-			"Missing build model. Provide via --model, --build-model, opencoder.json, or OPENCODER_BUILD_MODEL env var.",
+			"Missing build model. Provide via --model, --build-model, .opencode/opencoder/config.json, or OPENCODER_BUILD_MODEL env var.",
 		)
 	}
 

src/config.ts

@@ -6,14 +6,15 @@ import { existsSync, mkdirSync, readdirSync, renameSync, statSync, unlinkSync }
 import { join, resolve } from "node:path"
 import type { Paths } from "./types.ts"
 
-/** Name of the workspace directory */
-const OPENCODER_DIR = ".opencoder"
+/** Name of the workspace directory (inside .opencode) */
+const OPENCODE_DIR = ".opencode"
+const OPENCODER_SUBDIR = "opencoder"
 
 /**
  * Initialize all workspace paths for a project
  */
 export function initializePaths(projectDir: string): Paths {
-	const opencoderDir = join(resolve(projectDir), OPENCODER_DIR)
+	const opencoderDir = join(resolve(projectDir), OPENCODE_DIR, OPENCODER_SUBDIR)
 
 	return {
 		opencoderDir,
@@ -24,7 +25,7 @@ export function initializePaths(projectDir: string): Paths {
 		alertsFile: join(opencoderDir, "alerts.log"),
 		historyDir: join(opencoderDir, "history"),
 		ideasDir: join(opencoderDir, "ideas"),
-		configFile: join(resolve(projectDir), "opencoder.json"),
+		configFile: join(opencoderDir, "config.json"),
 	}
 }