A detailed, evolving description of user experience, UI structure, interaction flows, and behavioral conventions.
This document captures the intended feel of the application from the user's perspective. It describes what is "obviously true" in the interface based on earlier discussion and assumptions that flow naturally from the system’s goals.
Project Nexus is organized around four vertical columns and a multi-tab main panel. The interface is designed to feel like a hybrid between a project command center and a structured conversation workspace.
Layout:
[ Projects ] | [ Roadmap Lists ] | [ Chats ] | [ Main Panel: Chat / Terminal / Code ]
The leftmost three columns are persistent navigational layers. The rightmost, widest panel displays the currently active content.
Large screens keep all columns visible. Smaller screens may collapse columns into overlays, but only when explicitly toggled.
A list of ~20 projects, each with visual cues indicating state and activity.
Each project row includes:
- Name (primary, high-contrast)
- Icon (technology, domain, or custom badge)
- Category Tag (e.g., client work, research, maintenance)
- Activity Indicator using color:
- Gray — no agents working
- Yellow — agents waiting for the user
- Green — agents actively working
- Subtle Info Line (muted color blending into the background):
- recent change summary
- currently running thread or task focus
- Quick Filter field: filters visible projects without reordering
- Grouping by category or custom group
- Right-click context menu with options:
- View / Edit project details
- Change category
- Add to favorites
- Open project settings
- Quick access to favorited templates
Selecting a project may alter the theme of the UI to match the project’s color scheme. Themes can originate from:
- user's OS/browser preferred theme
- global user settings
- per-project overrides
(Renamed from "Task List List".)
A project may contain multiple roadmap lists that represent collections of tasks or phases. They bundle related chats and goals.
Each roadmap list displays:
- Title
- Tags / Attributes (e.g., feature, refactor, bugfix, research)
- Progress Percentage (derived from child chats or meta-status)
- Status Color (parallel to project colors):
- Gray — paused
- Yellow — waiting
- Green — active
- Red/Orange — error or blocked
- Subtle Info Text blending into the UI background:
- e.g., "3 chats active, focusing on API layer"
Right-clicking shows:
- Edit roadmap list
- Change tags or category
- Create new chat (from template)
- Open meta-status view
- Favorite templates (fast access)
Each roadmap list contains multiple chats. These chats may represent tasks, subthreads, investigations, or discussions.
Each chat row includes:
- Chat Title (primary text)
- Heuristic Status Line (subtle, e.g. "AI: Implemented part 2 of CLI")
- Percent Completion (derived from JSON-status logic and roadmap correlations)
- Status Color consistent with global schema
Every roadmap list has exactly one meta-chat, which appears at the top of the chat list, separated visually from regular chats.
The meta-chat:
- is responsible for interpreting task progress
- may execute pure JavaScript logic
- may also contain AI messages
- produces aggregated statuses for the roadmap list
It acts as the “brain” of the roadmap list.
The main panel is a horizontally split environment where the user performs actual work. Tabs control which mode is active.
Tabs:
- Chat – conversational interface with structure and controls
- Terminal – persistent tmux/screen-like session
- Code – file tree + viewer/editor (read-only or more advanced modes)
The top of the chat panel shows:
- Chat Title
- AI-generated status line (derived from JSON status and template logic)
- Relevant tasks from the parent roadmap list
- Link to template (if the chat was created from one)
- Action buttons:
- Mark as done
- Request status update
- Open meta-chat
- Open associated folder in terminal
Message types follow customizable thematic rules (color, border, icon, spacing):
- user
- assistant
- system
- status
- meta
Messages can be filtered:
- show all / only AI / only user / only status / only meta
Navigation shortcuts:
- previous user message
- next user message
- multiline input
- Enter sends, Shift+Enter adds line
- supports slash-commands with autocomplete (/status, /review, /plan, ...)
- future support for attaching files from the server-side file system
- Always corresponds to a persistent server-side PTY session
- Session begins in project root or a task-specific folder
- Play/Stop controls attach/detach
- Setting: auto-open terminal when entering a chat (off by default)
- Terminal commands are not mirrored to chat messages
The terminal is strictly a user tool, not automatically controlled by AI.
The code tab includes:
- File tree (project root or task-specific scope)
- Monaco-based code viewer/editor (initially read-only)
- Diff viewer for AI-generated patches
Diffs are displayed using conventional color highlights:
- green = added
- red = removed
- inline/side-by-side switching optional
Templates may include:
- title
- goal
- systemPrompt
- starterMessages
- optional JavaScript prompt (LLM-generated code)
- JavaScript logic (for interpreting JSON responses)
- key/value metadata
In certain templates, AI replies with a structured JSON object before every pause.
JSON includes:
- status
- progress
- activeTask
- errors
The JS logic in the template interprets JSON to produce:
- chat status
- roadmap list aggregated progress
- error flags
- meta-chat signals
The roadmap-level meta-chat:
- may run pure JS logic
- may request clarifying information from the AI
- always appears at the top of the chat list
- acts as the authoritative source of interpreted status
All projects and their substructures exist within a private Git repository.
Directory structure:
/projects/
PROJECT_ID/
meta.json
tasklists/
TASKLIST_ID/
meta.json
chats/
CHAT_ID/
messages.jsonl
workspace/
Snapshots come naturally from Git commits.
Metadata (status, progress, structural changes) is also stored or inferred from commit messages.
- User accounts based on username/password or keyfile
- Optionally tied to OS-level users
- Virtual user IDs possible
- Sessions recorded for auditability
- First-time setup triggers onboarding or guided flow
- User opens a project
- Creates a new roadmap list
- Adjusts roadmap list settings
- Creates a chat under that roadmap list
- Assigns the chat to a roadmap item
- Watches the initial AI-driven bootstrap conversation
- Uses chat, terminal, and code tabs to progress the task
- Meta-chat and JSON logic update roadmap status
- Git commits capture snapshot history
Default appearance is minimalist and unobtrusive.
Advanced details reveal themselves through:
- right-click actions
- expanding sections
- context-aware hints
Animations exist but do not distract. Sidebar animations are disabled on large screens.
Multiple themes are supported, including project-driven themes.
Project Nexus is a structured interaction environment that merges AI-assisted conversations, project decomposition, and operational tooling. It prioritizes clarity, predictability, and a sense of controlled progression. The system’s UX reflects a balance between minimalism and depth, allowing power users to reveal complexity only when needed while keeping routine workflows smooth and unobstructed.