Planning

Projects, Plans & Agents

Project state is the center of askTerminal. The app groups sessions, todos, EPICs, skills, agents, instructions, files, and git activity around a selected working directory.

Project Registry

Every selected project is registered in ~/.ask-terminal/projects.json. That file maps project names to absolute paths so app services and orchestration agents can refer to either codepro2 or /absolute/path/to/codepro2.

Kanban Sessions

KanbanManager merges session data from engine backends into TodoSession objects. A session can include title, summary, engine, working directory, branch name, last modified time, and todo items.

Engine	Data source	Task support
Claude Code	`~/.claude/projects` and `~/.claude/tasks`	Pending, in progress, completed
Codex	`~/.codex/state_5.sqlite` and session index/transcripts	No Claude-style task files

EPIC Planning

EPICs are project-scoped planning records stored as JSON lines at .ask-terminal/epics.jsonl inside the project. The UI renders them in open, assigned, in-progress, and completed lanes.

{
  "id": "a3f9c1d0",
  "title": "Implement settings sync",
  "status": "open",
  "owner": null,
  "body": "Markdown body with scope and notes.",
  "createdAt": "2026-05-23T10:00:00Z"
}

Auto Resume

AutoResumeService runs as an app-lifetime service. When enabled for a session, it scans every 30 seconds for assigned EPICs owned by that session, claims work, and sends an engine-specific resume command with an EPIC prompt. It reuses idle terminal windows when possible and launches a new terminal when needed.

Result reporting: Agents can complete or continue an EPIC by writing .ask-terminal/sessions/<sessionId>.result.json. The plans manager watches the result directory and applies valid updates.

Cross-Project EPIC Inbox

EpicInbox watches ~/.ask-terminal/inbox for JSON commands dropped by agents. It can create EPICs, assign owners, reopen EPICs, or set status. EpicAggregator writes a read-only cross-project snapshot to ~/.ask-terminal/state.json.

{"action":"create_epic","project":"codepro2","title":"Ship docs wiki","body":"Write bundled HTML documentation."}
{"action":"assign_epic","project":"codepro2","epicId":"a3f9c1d0","owner":"session-123"}
{"action":"set_status","project":"codepro2","epicId":"a3f9c1d0","status":"completed"}

Skills

Project skills are stored primarily in .ask-terminal/skills. The app can import skill folders, edit them, and mirror each skill to .claude/skills and .agents/skills so both engine ecosystems can consume the same SKILL.md format.

Agents

Project agents are stored primarily in .ask-terminal/agents. The app mirrors markdown agents to .claude/agents and converts them to TOML under .codex/agents for Codex compatibility.

Instructions And Rules

The Instructions view manages Claude memory, Codex memory, and project rules. It recognizes CLAUDE.md, AGENTS.md, and rule files under .claude/rules.

Worktrees

The project file tree and git tools understand main repositories and worktrees. Worktree creation uses an engine-aware branch prefix: cc for Claude and cx for Codex.

<- Terminal & Message Bus Analytics ->