This folder documents the current CodeAlta 1.0 implementation. It is not a backlog, comparison document, or archive of earlier design drafts. Public user documentation lives under site/; the files here are for maintainers who need to understand the code, runtime boundaries, and extension points.

See new-session provider choice for cached descriptor-only selection, exact enabled-host admission, original uncertainty retention and fresh catalog confirmation. Existing-session provider switching remains separate.

See commands, help and keyboard shortcuts for the Desktop command palette, help and key map, which follow the TUI's.

Provider/timeline localization and its scroll correction are independently accepted; Settings inventory translation is also independently accepted. Static project/session workflow translation awaits independent review. See WebView shell language for the bounded local-language shell/composer/palette/tab/browsing/inspection and static batch-deletion/Reminder/caller-ask/Settings inventory/project-session workflow controls, persistence semantics, untranslated areas and review limitations. Static About/log/reference presentation and its native-modal lifetime publication correction have scoped independent acceptance, with the split-layout process-exit gap retained. Advanced-session/retained-action/archived recovery presentation has bounded independent acceptance; see the localization evidence and literal-diagnostic boundary linked there. Selected-language relative session times and absolute timeline dates are implemented and independently accepted within bounded tests. The narrow App locale-switch check now tests reader-position retention separately from follow-to-bottom after legitimate translated notice wrapping; bounded verification passes. Exact source tooltips and literal recorded-date/Copy boundaries are documented in the same localization guide. See short-window composer layout for the scroll policy, retained-owner guarantees and responsive validation scope.

Read the documents in this order when onboarding or reviewing architecture-sensitive changes:

In development: Dual-head desktop parity and baseline tracks the approved desktop/TUI work separately from the current implementation documented here. Pending acceptance criteria are not shipped features or platform-support claims.

The isolated desktop boot entrypoint and its test-owned native fixtures are described in desktop native qualification, including preserved M0 evidence and explicit platform gaps.

The scoped Desktop prompt-image path documents PNG paste/preview/removal, editable local display titles, observed capability, typed owned image-only Send and its retention/filesystem limits.

flowchart TD
    Program[CodeAlta.Tui executable - altatui - Program + CodeAltaOwnedServices]
    Host[CodeAltaHost - shared runtime composition]
    Frontend[CodeAlta TUI frontend - CodeAltaApp + views + coordinators]
    LiveTool[CodeAlta.LiveTool - alta registry + dispatcher]
    Orchestration[CodeAlta.Orchestration - AgentHub + SessionRuntimeService]
    Agent[CodeAlta.Agent - session catalog, provider contracts, events, agent runtime]
    Providers[Provider packages - OpenAI-compatible, Anthropic, Google, direct HTTP]
    Catalog[CodeAlta.Catalog - projects, config, sessions, skills]
    Plugins[CodeAlta.Plugins - runtime + adapters]
    PluginApi[CodeAlta.Plugins.Abstractions - public authoring API]
    State[(~/.alta - config, cache, sessions, projects)]

    Program --> Host
    Program --> Frontend
    Program --> LiveTool
    Host --> Catalog
    Host --> Plugins
    Host --> Orchestration
    Host --> Agent
    Orchestration --> Agent
    Orchestration --> Catalog
    Orchestration --> Plugins
    Agent --> Providers
    Frontend --> Orchestration
    Frontend --> Catalog
    Frontend --> LiveTool
    Plugins --> PluginApi
    Catalog --> State
    Agent --> State

The altatui executable is the interactive terminal host, packaged as CodeAlta.Tui. The alta executable is the desktop host, packaged as CodeAlta and described in CodeAlta Desktop; the in-process agent tool is also named alta. Reusable session orchestration lives in runtime libraries, not in terminal controls. CodeAltaHost.CreateAsync is the shared composition entry point: it creates the catalog, plugin runtime, skill catalog, model-provider registry/initialization service, session catalog, AgentHub, SessionRuntimeService, and project-file search service. The TUI then composes views and frontend coordinators around those services.

src/CodeAlta.Hosting is not an active project in the solution. Shared host composition is CodeAlta.Orchestration.Hosting.CodeAltaHost.

CodeAlta's default global root is ~/.alta. Important roots are:

• config.toml for global chat/provider/plugin configuration;
• projects/ for project descriptors;
• sessions/yyyy/MM/dd/<session-id>.jsonl for CodeAlta-owned session journals and legacy session-view headers/state;
• sessions/traces/<session-id>.trace for optional protocol traces;
• cache/ for machine-local caches such as refreshed model metadata;
• auth/ for provider credential/token stores owned by provider auth managers;
• saved_prompts/ for unsent prompt drafts;
• ui-state.yaml for frontend view/session selection state;
• plugins/ and skills/ for user-scoped source plugins and skills;
• mcp.json for user-scoped MCP server connection definitions.

Project-local configuration and extensions live under <project>/.alta/, including <project>/.alta/config.toml, <project>/.alta/mcp.json, <project>/.alta/plugins/, and <project>/.alta/skills/.

• Describe current implementation first. Do not keep superseded plans in tracked docs.
• Verify behavior against src/**, tests, default config, and solution metadata before documenting it.
• Keep high-level documents linked from this page; add focused specs only when a stable implementation contract needs more detail.
• Prefer implementation terms used in current boundaries: model provider for selectable LLM configuration/runtime adapters, session for conversation/work units, and backend only for explicit legacy wire/config names or third-party terminal/backend concepts.
• Keep comparisons to other products and agents out of internal docs unless a configured provider/protocol name is required to explain CodeAlta behavior.