release: v0.2.4

[code-crusher]

Cut the v0.2.4 release. Folds the new -s / --system-prompt flag into the 0.2.4 section of CHANGELOG.md alongside the 'Working' spinner (which was the original content of that section).

What's in this release

Added

• -s / --system-prompt flag to override the default system prompt. Pass orbcode -s "<text>" (or --system-prompt "<text>", or --system-prompt="<text>" for values that start with -) to replace the built-in system prompt entirely for the session. Works in both the interactive TUI and headless mode (-p). When the override is active, AGENTS.md memory files and the skills catalog are skipped, since they live inside the default prompt.
• 'Working' spinner with elapsed timer. A ⠋ Working (Xs · esc to interrupt) spinner appears and stays visible through tool execution, covering the previously dead-air window.

Files changed

• src/core/agent.ts — added systemPromptOverride to AgentOptions; constructor uses it instead of buildSystemPrompt when set.
• src/headless.ts — runHeadless(prompt, yolo, systemPromptOverride?) threads the override into the Agent constructor.
• src/index.tsx — added takeSystemPrompt() supporting the = form, parses the flag, passes it to runHeadless and the TUI App. Updated printHelp.
• src/ui/App.tsx — App accepts systemPromptOverride; createAgent reads it from a ref so regenerated agents keep the override.
• CHANGELOG.md — -s flag entry added to the existing 0.2.4 section.
• package.json — no version bump (already 0.2.4).

Verification

• npm run typecheck → exit 0
• npm run build → exit 0

After merge

Per RELEASE.md, after the PR is merged into main, push the v0.2.4 tag to trigger the publish workflow:

git checkout main && git pull
git tag v0.2.4
git push origin v0.2.4

[matterai-app]

Summary By MatterAI

🔄 What Changed

Released version v0.2.4. This update introduces a --system-prompt (or -s) CLI flag allowing users to completely override the default agent instructions. It also includes UI responsiveness improvements by yielding the event loop before tool execution and updating status labels to "Working" during active processes.

🔍 Impact of the Change

Users can now fully customize the agent's behavior and persona, bypassing the default memory and skill loading logic. The TUI (Terminal User Interface) is more informative and less prone to freezing during heavy synchronous tool calls, providing a smoother user experience.

📁 Total Files Changed

Click to Expand

File	ChangeLog
Version Bump package.json	Incremented version to 0.2.4.
Agent Core src/core/agent.ts	Added prompt override logic and event loop yielding via setImmediate.
Headless Mode src/headless.ts	Updated runHeadless to support the new system prompt override.
CLI Entry src/index.tsx	Implemented custom flag parsing for -s and updated help documentation.
UI Component src/ui/App.tsx	Persisted the override across sessions using useRef and improved status indicators.

🧪 Test Added/Recommended

Recommended

• Unit Test: Add tests for takeSystemPrompt in src/index.tsx to ensure it correctly handles values starting with hyphens (e.g., --system-prompt="- instructions").
• Integration Test: Verify that the Agent class correctly skips loadMemoryFiles and loadSkills when an override is provided.

🔒 Security Vulnerabilities

No direct vulnerabilities detected. The system prompt override is a power-user feature; users are responsible for the content of the override.

⏳ Estimated code review effort

LOW (~10 minutes)

Tip

Quality Recommendations

1. Add validation to ensure systemPromptOverride is not an empty string if the flag is present

2. Consider adding a visual indicator in the UI when a custom system prompt is active

3. Add unit tests for the takeSystemPrompt utility to handle edge cases in CLI arguments

♫ Tanka Poem

Version point two four, 🚀
Custom prompts now lead the way, 🧠
Yielding for the UI,
Logic flows through silent gears, ⚙️
Science guides the code. 🔬

Sequence Diagram

sequenceDiagram
    participant U as User
    participant CLI as index.tsx
    participant App as App.tsx
    participant A as Agent.ts
    participant T as ToolExecutor

    U->>CLI: orbcode -s "Custom Prompt"
    CLI->>CLI: takeSystemPrompt(args)
    CLI->>App: render(systemPromptOverride)
    App->>A: new Agent(options)
    Note over A: If override exists, skip loading memory/skills
    A->>A: set systemPrompt = override
    U->>App: User submits prompt
    App->>A: chat()
    A->>A: Yield loop (setImmediate)
    A->>T: executeTool(name, args)
    T-->>A: toolResult
    A-->>App: onEvent("tool-end")
    App->>App: setBusyLabel("Working")

Loading

[matterai-app]

✅ Reviewed the changes: Clean feature PR adding -s / --system-prompt override. Reviewed all substantive changes: no issues found.