OpenDirect

OpenDirect 是一个面向 vibe directing 的 agentic creative project runtime。

产品形态是 CLI-first creative agent，使用方式应该接近 OpenCode / Claude Code：

cd my-creative-workspace
opendirect
opendirect run "write the opening scene"

它受到 OpenCode 这类 AI coding agent 的启发，但它的 source of truth 不是代码仓库，而是一个持续演化的创意工作目录。

OpenCode 修改代码仓库。
OpenDirect 修改创意项目文件和资产图谱。

direct.json、DIRECTOR.md、.opendirect/ 是 OpenDirect 在工作目录里的项目协议文件，类似 coding agent 读取 AGENTS.md、repo files 和 session state。用户不应该先理解“创建项目”这个内部概念；首次运行 CLI 时可以自动建立最小协议文件。

第一版产品与架构设计见 DESIGN.md。

开发就绪架构见 docs/development-architecture.md。

Harness 代码阅读笔记见 docs/harness-code-reading.md。

OpenCode 架构调研笔记见 docs/opencode-architecture-notes.md。

系统架构见 docs/architecture.md。

Harness 设计见 docs/harness.md。

Development

npm install
npm run check
npm test
npm run dev:mock-turn

Install

Install from npm:

npm install -g opendirect@latest

Then run it from any creative workspace:

mkdir my-show
cd my-show
opendirect
opendirect run "write the opening scene"
opendirect events

By default, OpenDirect uses openai/gpt-4.1 through the OpenAI Responses API tool-calling flow. Set your API key before starting:

export OPENAI_API_KEY="..."

opendirect starts an interactive terminal session:

opendirect> write the opening scene
opendirect> /status
opendirect> /model openai/gpt-4.1
opendirect> /provider openai-compatible https://api.example.com/v1 EXAMPLE_API_KEY
opendirect> /skill list
opendirect> /exit

The runtime flow is:

user direction
  -> project context + DIRECTOR.md + tool schemas
  -> model response
  -> model function/tool calls
  -> OpenDirect ToolOrchestrator executes tools
  -> tool outputs are sent back to the model
  -> final response + review payload

Default terminal output is human-readable:

tool: write_artifact
done: write_artifact - Wrote artifact artifacts/script/episode-001.md.

assistant:
Completed the requested workspace change.
Wrote artifact artifacts/script/episode-001.md.

changes:
- created: artifacts/script/episode-001.md

next: approve, request revision, or continue with another direction.

Use --json when you need the raw review payload:

opendirect run "write the opening scene" --json

Built-in commands:

• /help shows interactive commands.
• /status shows workspace, project, model, session and pending permissions.
• /provider shows the active model provider and available providers.
• /provider openai uses the OpenAI Responses API provider.
• /provider openai-compatible <base-url> <api-key-env> configures an OpenAI-compatible /chat/completions provider.
• /model shows the current model.
• /model <provider>/<model> stores the model in .opendirect/config.json.
• /skill list lists project skills available to the current workspace.
• /permissions shows pending permission requests.
• /approve <request-id> approves a pending permission request.
• /events shows runtime events.
• /exit exits the session.

Until the npm package is published, install from terminal:

curl -fsSL https://raw.githubusercontent.com/xexojay/opendirect/main/install.sh | bash

If the repository is private, the raw installer URL returns 404. Use an authenticated clone install instead:

git clone https://github.com/xexojay/opendirect.git ~/.opendirect-cli
cd ~/.opendirect-cli
npm install
npm run build
npm install -g .

If you prefer to inspect the installer first:

curl -fsSL https://raw.githubusercontent.com/xexojay/opendirect/main/install.sh

当前开发切片是 headless runtime skeleton：

• JSON schema validation for direct.json, assets-manifest.json, review payloads, and tool manifests.
• File-backed project loading from fixtures/minimal-project.
• Turn runtime with stream processing, tool routing, permission evaluation, tool state, event log, artifact write, and review emission.

Manual Testing

Run OpenDirect in an empty workspace:

PROJECT=/tmp/opendirect-test
rm -rf "$PROJECT"
mkdir -p "$PROJECT"
cd "$PROJECT"
npm --prefix /Users/xiexiongjie/opendirect run opendirect -- run "write the opening scene"

Or test from the repo with --cwd:

npm run opendirect -- run "write the opening scene" \
  --cwd "$PROJECT" \
  --session manual \
  --turn turn-001

Inspect events:

npm run opendirect -- events --cwd "$PROJECT" --session manual

Test permission flow:

npm run opendirect -- run "generate a video beat" --cwd "$PROJECT" --session manual --turn turn-002 --expensive
npm run opendirect -- permissions --cwd "$PROJECT" --session manual
npm run opendirect -- approve --cwd "$PROJECT" --session manual --request <permission-request-id>
npm run opendirect -- run "generate a video beat" --cwd "$PROJECT" --session manual --turn turn-003 --expensive