Stock Terminal

An AI-powered terminal stock tracker built with Textual. Watch symbols, view OHLCV candlestick charts, and generate AI trading signals — all from the terminal.

Features

• Symbol watchlist — add/remove/tag symbols, persisted in SQLite
• Candlestick charts — OHLCV charts with multiple timeframes (5m to 1w)
• AI trading signals — multi-timeframe analysis via DeepSeek or Gemini LLMs
• Custom agents — define signal personas as plain Markdown files
• Company knowledge — per-symbol notes folder injected into AI signal prompts
• Recommendation history — browse and filter past AI signal recommendations
• Multiple data providers — Yahoo Finance (default) and TwelveData
• In-app log viewer — press L to inspect the live log without leaving the TUI
• Secure key storage — API keys stored via OS keyring, never in plain files

Requirements

• Python 3.13+
• uv package manager

Installation

git clone https://github.com/your-username/stock-terminal.git
cd stock-terminal
uv venv
uv sync
uv run python main.py

Key Bindings

Press ? in the app for the full grouped shortcut list. Ctrl+P opens the Textual command palette (Keys, Quit, theme, etc.).

Watchlist

Key	Action
Enter	Open chart for selected symbol
r	Refresh signal for selected row
k	Open knowledge folder for selected symbol

Configuration

Key	Action
s	Manage watched symbols
p	Switch data provider
c	Set LLM connector + API key
a	Manage AI agents
i	Signal settings (timeframes)

Tools

Key	Action
h	Recommendation history
l	In-app log viewer

App

Key	Action
?	Show all keyboard shortcuts
Ctrl+P	Command palette
q	Quit

AI Signals

Signals are generated by sending multi-timeframe OHLCV data to an LLM. Each signal includes a BUY / SELL / HOLD recommendation with optional stop-loss, take-profit, and target date.

Setup

1. Press c to open the connector picker, choose DeepSeek or Gemini, and enter your API key.
2. Press i to configure the fast and slow timeframes used for analysis.
3. Open a symbol chart — the signal fetches automatically on the configured interval.

Supported connectors

Connector	Key field
DeepSeek	deepseek_api_key
Gemini	gemini_api_key
Claude	claude_api_key

Custom Agents

Agents are Markdown files stored in ~/.stock-terminal/agents/. Their content is prepended to every signal prompt, letting you define a trading style, risk profile, or analytical framework.

Manage agents from the Agents screen (a): create, edit, enable, or disable. Only one agent can be active at a time.

Company Knowledge

Each watched symbol has its own folder under ~/.stock-terminal/knowledge/{SYMBOL}/. Drop research notes there as .txt, .md, or .pdf files — their content is injected into the LLM prompt when generating signals for that symbol.

Press k on the dashboard with a symbol selected to open its folder in your file manager. Folders are created automatically when you add a symbol to the watchlist.

Data Providers

Provider	Notes
yahoo	Default, no API key required
twelvedata	Free and premium tiers supported

Switch providers at runtime with p.

Storage

All persistent data lives under ~/.stock-terminal/:

~/.stock-terminal/
├── stock.db        # SQLite database
├── app.log         # Rotating log (1 MB × 3 backups)
├── agents/         # Custom agent Markdown files
└── knowledge/      # Per-symbol research notes (.txt, .md, .pdf)
    ├── AAPL/
    └── MSFT/

Development

# Run tests
uv run pytest

# Add a dependency
uv add <package>

Extending the app

• New data source — subclass DataSource in data/, register with @register_source("<name>"), add a matching adapter in data/adapters/.
• New LLM connector — subclass BaseAgentConnector in connectors/, register with @register_connector("<name>", key_field="<keyring_field>").
• Database migrations — add migrations/000N.description.sql; applied automatically on next startup via yoyo-migrations.

License

MIT