FlossWare's shared control plane for configuring coding agents and independently usable FlossWare AI capabilities. Supported installation targets include Fedora/RHEL derivatives, Debian-family Linux, FreeBSD, Windows, and Termux.
A normal user does not need to clone this repository. The bootstrap installer downloads the managed artifacts/source archive and installs the control plane into the user's FlossWare directory:
curl -fsSL https://raw.githubusercontent.com/FlossWare/coding-agent-setup/main/install.sh | bash
flossware-ai tuiFor a local checkout, contributor build, or explicit source fallback, use the repository's scripts/install.sh and set FLOSSWARE_USE_SOURCE=true when source checkout behavior is desired.
The managed runtime lives at ~/.flossware/ai (or the platform-appropriate user data location). Reinstallation and cleanup never require manually deleting that directory.
./scripts/install.sh --reinstall
./scripts/install.sh --clean--clean removes only the managed FlossWare AI installation. It does not remove project instruction files, native agent credentials, or provider credentials.
For a complete operator workflow, read docs/operator-guide.md. It covers bootstrap installation, the Setup Control Center, agents, capabilities, accounts/models, runtimes, profiles, validation, mouse/keyboard operation, contextual status, reinstall/cleanup, and troubleshooting.
The consumer path is artifact-first and repository-independent:
curl bootstrap
|
+--> coding-agent-ai package artifact
|
+--> coding-agent-setup GitHub source archive
|
+--> managed install
|
+--> flossware-ai tui / doctor / dogfood
No Git clone is required for a normal installation. FLOSSWARE_USE_SOURCE=true is an explicit contributor/developer escape hatch for source checkout and editable installation. See docs/artifacts.md.
Loom AI is the complete external orchestration platform, but Loom is optional. FlossWare AI libraries remain independently usable from Claude Code, Crush, Codex, OpenCode, Cursor, and other agents.
Agent
|
+--> individual FlossWare capability
| model-router / RAG / search / evaluation / ...
|
+--> Loom AI (complete orchestration platform)
The setup layer provides common configuration, profiles, account/model discovery, credential-source references, MCP integration, CLI, and the operator Setup TUI. It does not copy provider secrets or human identity data into generated files.
flossware-ai tui is a terminal-based operator interface. The preview below is a representative terminal-state rendering based on the repository's documented TUI transcripts, not a desktop GUI mockup. Actual appearance varies with terminal size, font, and platform.
The TUI provides a contextual status line above its key legend. Move with arrow keys or mouse hover to see information about the current item. Hovering is informational only; Enter/Space/click performs the action. Status text never contains credentials or PII.
The repository also keeps the underlying terminal-state transcripts in screenshots/.
docs/operator-guide.md— canonical end-to-end operator guidedocs/setup-tui.md— current Setup TUI behavior, screens, keyboard/mouse operation, contextual statusdocs/cli-reference.md— CLI commands and validation lifecycledocs/profile-schema.md— profile fields, policy, and security invariantsdocs/discovery.md— provider/account/model discovery lifecycle and status statesdocs/troubleshooting.md— common failures and recovery
docs/architecture.md— setup control-plane architecturedocs/agent-integrations.md— coding-agent and MCP integration modeldocs/credentials-and-accounts.md— profiles, accounts, credential safety, and status statesdocs/privacy.md— mandatory non-PII and secret-handling invariantdocs/SECURITY.md— security policydocs/artifacts.md— artifact-first installation and explicit source fallbackdocs/platforms.md— Fedora/RHEL, Debian, FreeBSD, Termux, and Windows supportdocs/decorators.md— declarative decorator pipeline and orderingdocs/container-runtimes.md— Podman/Docker execution backends
flossware-ai agents
flossware-ai agents setup crush
flossware-ai components
flossware-ai components model-router-ai
flossware-ai accounts --verify
flossware-ai models --refresh
flossware-ai providers
flossware-ai runtime list
flossware-ai runtime status
flossware-ai runtime select podman
flossware-ai runtime select docker
flossware-ai runtime auto
flossware-ai doctor
flossware-ai dogfood --strict
flossware-ai tuiSee docs/cli-reference.md for the canonical command reference.
Supported agents include Claude Code, Cursor, OpenCode, Crush, Codex, Aider, Cline, Roo Code, Gemini CLI, GitHub Copilot, Windsurf, Amazon Q Developer, and Kiro. Shared AGENTS.md consumers intentionally use one common project instruction file.
Profiles are user-defined policy boundaries, not hardcoded organizational identities. The public repository ships only a neutral default profile. Users can create profiles such as personal, work, redhat, government, client-a, or any other name appropriate to their environment.
A profile controls which providers, accounts, models, local models, and FlossWare capabilities are permitted for that workload. The repository does not assume that any particular employer, organization, provider, or compliance regime applies to every user.
For the exact shipped schema and policy semantics, see docs/profile-schema.md.
- configured: a credential source is present
- verified: authentication/credential validation succeeded
- discovered: an authenticated provider advertised the account/model
- available: discovered and permitted by the active profile
- ready: credentials, policy, and connectivity checks pass
- active: selected for the current workload
- blocked: policy or platform prevents use
See docs/discovery.md.
FlossWare uses explicitly enabled decorators/interceptors/middleware for cross-cutting behavior such as retries, circuit breaking, observability, auditing, caching, evaluation, security/policy enforcement, structured-output validation, and token/cost accounting. This follows Engineering Standards ADR-0006.
The TUI configures these declaratively under Components → Cross-Cutting Behavior. Users can enable/disable decorators, edit their policy settings, and reorder the stack when ordering affects semantics. The runtime translates that policy into the appropriate decorator/interceptor/middleware implementation.
Decorator configuration is provider-neutral and contains no secrets or human identity data. Profile defaults may supply policy, while component configuration provides explicit opt-in or override.
Podman and Docker are supported as execution backends. On Linux, Podman is preferred when healthy, while Docker is fully supported. Windows supports Docker Desktop and Podman where available. FreeBSD and Termux report a runtime only when it is actually reachable; the setup layer does not claim native container support where an external VM or compatibility layer is required. Native execution remains available when no runtime is configured.
FlossWare managed configuration is non-identifying and secret-free. API keys, OAuth tokens, passwords, cookies, email addresses, employee/customer identifiers, phone numbers, and other PII are not persisted in profiles, account metadata, generated agent files, MCP definitions, logs, or diagnostics.
Credential references such as environment:OPENAI_API_KEY identify where a secret is obtained; they are not secret values. Account aliases must be opaque local identifiers, such as openai-account-1, rather than human names, emails, or employee identifiers.
See docs/privacy.md and docs/SECURITY.md.
- FlossWare/loom-ai — complete orchestration platform
- FlossWare/model-router-ai — provider/account/model routing
- FlossWare/curses-themes — shared TUI themes
- FlossWare/coding-agent-ai — coding-agent runtime
MIT