helix-tui

Helix is an AI-driven decision engine that autonomously executes systematic trading strategies to compound capital.

helix-tui is a Go CLI + TUI trading cockpit for Alpaca with:

• risk-gated order execution
• autonomous execution agents (heuristic and llm)
• low-frequency strategy analyst overseer
• SQLite-backed persistence (events, equity history, strategy memory)

Disclaimer

This project is an AI-generated, experimental toy project for educational/development use only. It is not investment advice and is not production-ready trading software. You are solely responsible for all configuration, operation, compliance, and losses. Use at your own risk.

Documentation

• Architecture
• New user onboarding
• Operator playbook
• Implementation roadmap
• Config template

Runtime Model (Important)

• Runtime broker is Alpaca.
• Select environment via [alpaca].env = "paper" | "live".
• The in-memory paper broker adapter exists for tests only.

Prerequisites

• Go 1.24+
• Alpaca account/API keys (paper recommended)
• Optional: OpenAI API key for [agent].type = "llm" and strategy analyst

Quick Start

1. Create your config:

Copy-Item config.example.toml config.toml

If config.toml is missing, startup will prompt you to create it automatically from config.example.toml.

1. Keep safe defaults while validating:

• [alpaca].env = "paper"
• mode = "manual" or mode = "assist"
• if using mode = "auto", set [agent].dry_run = true first

1. Run with TUI:

go run ./cmd/helix -config=config.toml

1. Optional headless mode:

go run ./cmd/helix -config=config.toml -headless

1. Print version:

go run ./cmd/helix -version

Configuration

Config source precedence:

1. built-in defaults
2. config.toml
3. env vars (APCA_API_KEY_ID, APCA_API_SECRET_KEY, APCA_API_DATA_URL, OPENAI_API_KEY)
4. CLI flags (-config, -headless, -version)

Key config areas:

• mode: manual | assist | auto
• [identity]: human_name, human_alias, agent_name
• [alpaca]: env/endpoints/feed + credentials (or env/keyring)
• [risk]: max trade/day notional
• [compliance]: PDT/GFV guardrails
• [agent]: runtime cadence + intent limits + low power
• [agent.heuristic]: heuristic-only sizing/trigger settings
• [agent.llm]: model/prompt/timeout/context logging
• [strategy] and [strategy.llm]: overseer cadence + model/prompt
• [logging]: structured log file/mode/level
• [database]: SQLite state path

Credentials

You can provide credentials via:

• environment variables
• config.toml
• OS keyring ([keyring].use = true)

Recommended: enable keyring and avoid keeping secrets in config.toml.

Runtime Modes

• manual: no autonomous order execution
• assist: agent proposes intents, operator approves manually
• auto: agent executes via the same risk/compliance path as manual commands

Safe progression:

1. manual + watch behavior
2. assist
3. auto with [agent].dry_run = true
4. auto with dry-run disabled only after validation

TUI Commands

• buy <SYM> <QTY>
• sell <SYM> <QTY>
• cancel <ORDER_ID|ORDER_ID_PREFIX|#ROW>
• flatten
• sync
• watch list|add <SYM>|remove <SYM>|sync
• events up|down|top|tail [N]
• strategy run|status|approve <ID>|reject <ID>|archive <ID>
• strategy proposal status|list|apply <ID>|reject <ID>
• strategy chat status|list|new <TITLE>|use <ID>|say <MESSAGE>
• tab overview|strategy|system|logs
• q
• ? toggle help

Safety/Execution Notes

• Watchlist is the effective trading allowlist.
• LLM output only proposes intents; engine risk/compliance gates still decide execution.
• Compliance gate can reject orders (e.g., PDT/GFV protections) with explicit rejection reasons.
• Strategy mode can constrain autonomous execution to active plan recommendations.
• Strategy chat is advisory-only and does not place orders directly.
• Copilot proposals are staged and require explicit strategy proposal apply before taking effect.
• Low-power mode reduces autonomous activity outside market hours.

Development

Run checks before committing:

go test ./...
go build ./cmd/helix
go run golang.org/x/vuln/cmd/govulncheck@latest ./...

Releases

This repo is wired for GoReleaser.

• Config: .goreleaser.yaml
• GitHub workflow: .github/workflows/release.yml (runs on tags like v1.2.3)
• Release archives include: binary + README.md + LICENSE + config.example.toml + docs/

Local smoke checks:

go run github.com/goreleaser/goreleaser/v2@latest check
go run github.com/goreleaser/goreleaser/v2@latest release --snapshot --clean

Create a release:

git tag v0.1.0
git push origin v0.1.0