altimate-code 0.0.1 → 0.4.7

package/CHANGELOG.md

@@ -0,0 +1,316 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.4.1] - 2026-03-16
+## [0.4.2] - 2026-03-18
+
+### Breaking Changes
+
+- **Python engine eliminated** — all 73 tool methods now run natively in TypeScript. No Python, pip, venv, or `altimate-engine` installation required. Fixes #210.
+
+### Added
+
+- `@altimateai/drivers` shared workspace package with 10 database drivers (Snowflake, BigQuery, PostgreSQL, Databricks, Redshift, MySQL, SQL Server, Oracle, DuckDB, SQLite)
+- Direct `@altimateai/altimate-core` napi-rs bindings — SQL analysis calls go straight to Rust (no Python intermediary)
+- dbt-first SQL execution — automatically uses `profiles.yml` connection when in a dbt project
+- Warehouse telemetry (5 event types: connect, query, introspection, discovery, census)
+- 340+ new tests including E2E tests against live Snowflake, BigQuery, and Databricks accounts
+- Encrypted key-pair auth support for Snowflake (PKCS8 PEM with passphrase)
+- Comprehensive driver documentation at `docs/docs/drivers.md`
+
+### Fixed
+
+- Python bridge connection failures for UV, conda, and non-standard venv setups (#210)
+- SQL injection in finops/schema queries (parameterized queries + escape utility)
+- Credential store no longer saves plaintext passwords
+- SSH tunnel cleanup on SIGINT/SIGTERM
+- Race condition in connection registry for concurrent access
+- Databricks DATE_SUB syntax
+- Redshift describeTable column name
+- SQL Server describeTable includes views
+- Dispatcher telemetry wrapped in try/catch
+- Flaky test timeouts
+
+### Removed
+
+- `packages/altimate-engine/` — entire Python package (~17,000 lines)
+- `packages/opencode/src/altimate/bridge/` — JSON-RPC bridge
+- `.github/workflows/publish-engine.yml` — PyPI publish workflow
+
+### Added
+
+- Local-first tracing system replacing Langfuse (#183)
+
+### Fixed
+
+- Engine not found when user's project has `.venv` in cwd — managed venv now takes priority (#199)
+- Missing `[warehouses]` pip extra causing FinOps tools to fail with "snowflake-connector-python not installed" (#199)
+- Engine install trusting stale manifest when venv/Python binary was deleted (#199)
+- Extras changes not detected on upgrade — manifest now tracks installed extras (#199)
+- Windows path handling for dev/cwd venv resolution (#199)
+- Concurrent bridge startup race condition — added `pendingStart` mutex (#199)
+- Unhandled spawn `error` event crashing host process on invalid Python path (#199)
+- Bridge hung permanently after ping failure — child process now cleaned up (#199)
+- `restartCount` incorrectly incremented on signal kills, prematurely disabling bridge (#199)
+- TUI prompt corruption from engine bootstrap messages writing to stderr (#180)
+- Tracing exporter timeout leaking timers (#191)
+- Feedback submission failing when repo labels don't exist (#188)
+- Pre-release security and resource cleanup fixes for tracing (#197)
+
+## [0.4.0] - 2026-03-15
+
+### Added
+
+- Data-viz skill for data storytelling and visualizations (#170)
+- AI Teammate training system with learn-by-example patterns (#148)
+
+### Fixed
+
+- Sidebar shows "OpenCode" instead of "Altimate Code" after upstream merge (#168)
+- Prevent upstream tags from polluting origin (#165)
+- Show welcome box on first CLI run, not during postinstall (#163)
+
+### Changed
+
+- Engine version bumped to 0.4.0
+
+## [0.3.1] - 2026-03-15
+
+### Fixed
+
+- Database migration crash when upgrading from v0.2.x — backfill NULL migration names for Drizzle beta.16 compatibility (#161)
+- Install banner not visible during `npm install` — moved output from stdout to stderr (#161)
+- Verbose changelog dump removed from CLI startup (#161)
+- `altimate upgrade` detection broken — `method()` and `latest()` referenced upstream `opencode-ai` package names instead of `@altimateai/altimate-code` (#161)
+- Brew formula detection and upgrade referencing `opencode` instead of `altimate-code` (#161)
+- Homebrew tap updated to v0.3.0 (was stuck at 0.1.4 due to expired `HOMEBREW_TAP_TOKEN`) (#161)
+- `.opencode/memory/` references in docs updated to `.altimate-code/memory/` (#161)
+- Stale `@opencode-ai/plugin` reference in CONTRIBUTING.md (#161)
+
+### Changed
+
+- CI now uses path-based change detection to skip unaffected jobs (saves ~100s on non-TS changes) (#161)
+- Release workflow gated on test job passing (#157)
+- Upstream merge restricted to published GitHub releases only (#150)
+
+## [0.3.0] - 2026-03-15
+
+### Added
+
+- AI-powered prompt enhancement (#144)
+- Altimate Memory — persistent cross-session memory with TTL, namespaces, citations, and audit logging (#136)
+- Upstream merge with OpenCode v1.2.26 (#142)
+
+### Fixed
+
+- Sentry review findings from PR #144 (#147)
+- OAuth token refresh retry and error handling for idle timeout (#133)
+- Welcome banner on first CLI run after install/upgrade (#132)
+- `@altimateai/altimate-code` npm package name restored after upstream rebase
+- Replace `mock.module()` with `spyOn()` to fix 149 test failures (#153)
+
+### Changed
+
+- Rebrand user-facing references to Altimate Code (#134)
+- Bump `@modelcontextprotocol/sdk` dependency (#139)
+- Engine version bumped to 0.3.0
+
+## [0.2.5] - 2026-03-13
+
+### Added
+
+- `/feedback` command and `feedback_submit` tool for in-app user feedback (#89)
+- Datamate manager — dynamic MCP server management (#99)
+- Non-interactive mode for `mcp add` command with input validation
+- `mcp remove` command
+- Upstream merge with OpenCode v1.2.20
+
+### Fixed
+
+- TUI crash after upstream merge (#98)
+- `GitlabAuthPlugin` type incompatibility in plugin loader (#92)
+- All test failures from fork restructure (#91)
+- CI/CD workflow paths updated from `altimate-code` to `opencode`
+- Fallback to global config when not in a git repo
+- PR standards workflow `TEAM_MEMBERS` ref corrected from `dev` to `main` (#101)
+
+### Changed
+
+- Removed self-hosted runners from public repo CI (#110)
+- Migrated CI/release to ARC runners (#93, #94)
+- Reverted Windows tests to `windows-latest` (#95)
+- Engine version bumped to 0.2.5
+
+## [0.2.4] - 2026-03-04
+
+### Added
+
+- E2E tests for npm install pipeline: postinstall script, bin wrapper, and publish output (#50)
+
+## [0.2.3] - 2026-03-04
+
+### Added
+
+- Postinstall welcome banner and changelog display after upgrade (#48)
+
+### Fixed
+
+- Security: validate well-known auth command type before execution, add confirmation prompt (#45)
+- CI/CD: SHA-pin all GitHub Actions, per-job least-privilege permissions (#45)
+- MCP: fix copy-paste log messages, log init errors, prefix floating promises (#45)
+- Session compaction: clean up compactionAttempts on abort to prevent memory leak (#45)
+- Telemetry: retry failed flush events once with buffer-size cap (#45, #46)
+- Telemetry: flush events before process exit (#46)
+- TUI: resolve worker startup crash from circular dependency (#47)
+- CLI: define ALTIMATE_CLI build-time constants for correct version reporting (#41)
+- Address 4 issues found in post-v0.2.2 commits (#49)
+- Address remaining code review issues from PR #39 (#43)
+
+### Changed
+
+- CI/CD: optimize pipeline with caching and parallel builds (#42)
+
+### Docs
+
+- Add security FAQ (#44)
+
+## [0.2.2] - 2026-03-05
+
+### Fixed
+
+- Telemetry init: `Config.get()` failure outside Instance context no longer silently disables telemetry
+- Telemetry init: called early in CLI middleware and worker thread so MCP/engine/auth events are captured
+- Telemetry init: promise deduplication prevents concurrent init race conditions
+- Telemetry: pre-init events are now buffered and flushed (previously silently dropped)
+- Telemetry: user email is SHA-256 hashed before sending (privacy)
+- Telemetry: error message truncation standardized to 500 chars across all event types
+- Telemetry: `ALTIMATE_TELEMETRY_DISABLED` env var now actually checked in init
+- Telemetry: MCP disconnect reports correct transport type instead of hardcoded `stdio`
+- Telemetry: `agent_outcome` now correctly reports `"error"` outcome for failed sessions
+
+### Changed
+
+- Auth telemetry events use session context when available instead of hardcoded `"cli"`
+
+## [0.2.1] - 2026-03-05
+
+### Added
+
+- Comprehensive telemetry instrumentation: 25 event types across auth, MCP servers, Python engine, provider errors, permissions, upgrades, context utilization, agent outcomes, workflow sequencing, and environment census
+- Telemetry docs page with event table, privacy policy, opt-out instructions, and contributor guide
+- AppInsights endpoint added to network firewall documentation
+- `categorizeToolName()` helper for tool classification (sql, schema, dbt, finops, warehouse, lineage, file, mcp)
+- `bucketCount()` helper for privacy-safe count bucketing
+
+### Fixed
+
+- Command loading made resilient to MCP/Skill initialization failures
+
+### Changed
+
+- CLI binary renamed from `altimate-code` to `altimate`
+
+## [0.2.0] - 2026-03-04
+
+### Added
+
+- Context management: auto-compaction with overflow recovery, observation masking, and loop protection
+- Context management: data-engineering-aware compaction template preserving warehouse, schema, dbt, and lineage context
+- Context management: content-aware token estimation (code, JSON, SQL, text heuristics)
+- Context management: observation masking replaces pruned tool outputs with fingerprinted summaries
+- Context management: provider overflow detection for Azure OpenAI patterns
+- CLI observability: telemetry module with session, generation, tool call, and error tracking
+- `/discover` command for data stack setup with project_scan tool
+- User documentation for context management configuration
+
+### Fixed
+
+- ContextOverflowError now triggers automatic compaction instead of a dead-end error
+- `isOverflow()` correctly reserves headroom for models with separate input/output limits
+- `NamedError.isInstance()` no longer crashes on null input
+- Text part duration tracking now preserves original start timestamp
+- Compaction loop protection: max 3 consecutive attempts per turn, counter resets between turns
+- Negative usable context guard for models where headroom exceeds base capacity
+
+### Changed
+
+- Removed cost estimation and complexity scoring bindings
+- Docs: redesigned homepage with hero, feature cards, and pill layouts
+- Docs: reorganized sidebar navigation for better discoverability
+
+## [0.1.10] - 2026-03-03
+
+### Fixed
+
+- Build: resolve @opentui/core parser.worker.js via import.meta.resolve for monorepo hoisting
+- Build: output binary as `altimate-code` instead of `opencode`
+- Publish: update Docker/AUR/Homebrew references from anomalyco/opencode to AltimateAI/altimate-code
+- Publish: make Docker/AUR/Homebrew steps non-fatal
+- Bin wrapper: look for `@altimateai/altimate-code-*` scoped platform packages
+- Postinstall: resolve `@altimateai` scoped platform packages
+- Dockerfile: update binary paths and names
+
+## [0.1.9] - 2026-03-02
+
+### Fixed
+
+- Build: fix solid-plugin import to use bare specifier for monorepo hoisting
+- CI: install warehouse extras for Python tests (duckdb, boto3, etc.)
+- CI: restrict pytest collection to tests/ directory
+- CI: fix all ruff lint errors in Python engine
+- CI: fix remaining TypeScript test failures (agent rename, config URLs, Pydantic model)
+- Update theme schema URLs and documentation references to altimate-code.dev
+
+## [0.1.8] - 2026-03-02
+
+### Changed
+
+- Rename npm scope from `@altimate` to `@altimateai` for all packages
+- Wrapper package is now `@altimateai/altimate-code` (no `-ai` suffix)
+
+### Fixed
+
+- CI: test fixture writes config to correct filename (`altimate-code.json`)
+- CI: add `dev` optional dependency group to Python engine for pytest/ruff
+
+## [0.1.7] - 2026-03-02
+
+### Changed
+
+- Improve TUI logo readability: redesign M, E, T, I letter shapes
+- Add two-tone logo color: ALTIMATE in peach, CODE in purple
+
+### Fixed
+
+- Release: npm publish glob now finds scoped package directories
+- Release: PyPI publish skips existing versions instead of failing
+
+## [0.1.5] - 2026-03-02
+
+### Added
+
+- Anthropic OAuth plugin ported in-tree
+- Docs site switched from Jekyll to Material for MkDocs
+
+### Fixed
+
+- Build script: restore `.trim()` on models API JSON to prevent syntax error in generated `models-snapshot.ts`
+- Build script: fix archive path for scoped package names in release tarball/zip creation
+
+## [0.1.0] - 2025-06-01
+
+### Added
+
+- Initial open-source release
+- SQL analysis and formatting via Python engine
+- Column-level lineage tracking
+- dbt integration (profiles, lineage, `+` operator)
+- Warehouse connectivity (Snowflake, BigQuery, Databricks, Postgres, DuckDB, MySQL)
+- AI-powered SQL code review
+- TUI interface with Solid.js
+- MCP (Model Context Protocol) server support
+- Auto-bootstrapping Python engine via uv

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Altimate AI
+Copyright (c) 2025 opencode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,235 @@
+<div align="center">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/docs/assets/images/altimate-code-banner.png" />
+  <img src="docs/docs/assets/images/altimate-code-banner.png" alt="altimate-code" width="600" />
+</picture>
+
+**The open-source data engineering harness.**
+
+The intelligence layer for data engineering AI — 99+ deterministic tools for SQL analysis,
+column-level lineage, dbt, FinOps, and warehouse connectivity across every major cloud platform.
+
+Run standalone in your terminal, embed underneath Claude Code or Codex, or integrate
+into CI pipelines and orchestration DAGs. Precision data tooling for any LLM.
+
+[![npm](https://img.shields.io/npm/v/@altimateai/altimate-code)](https://www.npmjs.com/package/@altimateai/altimate-code)
+[![npm](https://img.shields.io/npm/v/@altimateai/altimate-core)](https://www.npmjs.com/package/@altimateai/altimate-core)
+[![npm downloads](https://img.shields.io/npm/dm/@altimateai/altimate-code)](https://www.npmjs.com/package/@altimateai/altimate-code)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+[![CI](https://github.com/AltimateAI/altimate-code/actions/workflows/ci.yml/badge.svg)](https://github.com/AltimateAI/altimate-code/actions/workflows/ci.yml)
+[![Slack](https://img.shields.io/badge/Slack-Join%20Community-4A154B?logo=slack)](https://altimate.ai/slack)
+[![Docs](https://img.shields.io/badge/docs-altimateai.github.io-blue)](https://altimateai.github.io/altimate-code)
+
+</div>
+
+---
+
+## Install
+
+```bash
+# npm (recommended)
+npm install -g @altimateai/altimate-code
+
+# Homebrew
+brew install AltimateAI/tap/altimate-code
+```
+
+Then — in order:
+
+**Step 1: Configure your LLM provider** (required before anything works):
+```bash
+altimate        # Launch the TUI
+/connect        # Interactive setup — choose your provider and enter your API key
+```
+
+> **No API key?** Select **Codex** in the `/connect` menu — it's built-in and requires no setup.
+
+Or set an environment variable directly:
+```bash
+export ANTHROPIC_API_KEY=your_key   # Anthropic Claude
+export OPENAI_API_KEY=your_key      # OpenAI
+```
+
+**Step 2 (optional): Auto-detect your data stack** (read-only, safe for production connections):
+```bash
+altimate /discover
+```
+
+`/discover` auto-detects dbt projects, warehouse connections (from `~/.dbt/profiles.yml`, Docker, environment variables), and installed tools (dbt, sqlfluff, airflow, dagster, and more). Skip this and start building — you can always run it later.
+
+> **Zero Python setup required.** On first run, the CLI automatically downloads [`uv`](https://github.com/astral-sh/uv), creates an isolated Python environment, and installs the data engine with all warehouse drivers. No `pip install`, no virtualenv management.
+
+## Why a specialized harness?
+
+General AI coding agents can edit SQL files. They cannot *understand* your data stack.
+altimate gives any LLM a deterministic data engineering intelligence layer —
+no hallucinated SQL advice, no guessing at schema, no missed PII.
+
+| Capability | General coding agents | altimate |
+|---|---|---|
+| SQL anti-pattern detection | None | 19 rules, confidence-scored |
+| Column-level lineage | None | Automatic from SQL, any dialect |
+| Schema-aware autocomplete | None | Live-indexed warehouse metadata |
+| Cross-dialect SQL translation | None | Snowflake ↔ BigQuery ↔ Databricks ↔ Redshift |
+| FinOps & cost analysis | None | Credits, expensive queries, right-sizing |
+| PII detection | None | 30+ regex patterns, 15 categories |
+| dbt integration | Basic file editing | Manifest parsing, test gen, model scaffolding, lineage |
+| Data visualization | None | Auto-generated charts from SQL results |
+| Observability | None | Local-first tracing of AI sessions and tool calls |
+
+> **Benchmarked precision:** 100% F1 on SQL anti-pattern detection (1,077 queries, 19 rules, 0 false positives).
+> 100% edge-match on column-level lineage (500 queries, 13 categories).
+> [See methodology →](experiments/BENCHMARKS.md)
+
+**What the harness provides:**
+- **SQL Intelligence Engine** — deterministic SQL parsing and analysis (not LLM pattern matching). 19 rules, 100% F1, 0 false positives. Built for data engineers who've been burned by hallucinated SQL advice.
+- **Column-Level Lineage** — automatic extraction from SQL across dialects. 100% edge-match on 500 benchmark queries.
+- **Live Warehouse Intelligence** — indexed schemas, query history, and cost data from your actual warehouse. Not guesses.
+- **dbt Native** — manifest parsing, test generation, model scaffolding, medallion patterns, impact analysis
+- **FinOps** — credit consumption, expensive query detection, warehouse right-sizing, idle resource cleanup
+- **PII Detection** — 15 categories, 30+ regex patterns, enforced pre-execution
+
+**Works seamlessly with Claude Code and Codex.** altimate is the data engineering tool layer — use it standalone in your terminal, or mount it as the harness underneath whatever AI agent you already run. The two are complementary.
+
+altimate is a fork of [OpenCode](https://github.com/anomalyco/opencode) rebuilt for data teams. Model-agnostic — bring your own LLM or run locally with Ollama.
+
+## Quick demo
+
+```bash
+# Auto-detect your data stack (dbt projects, warehouse connections, installed tools)
+> /discover
+
+# Analyze a query for anti-patterns and optimization opportunities
+> Analyze this query for issues: SELECT * FROM orders JOIN customers ON orders.id = customers.order_id
+
+# Translate SQL across dialects
+> /sql-translate this Snowflake query to BigQuery: SELECT DATEADD(day, 7, current_date())
+
+# Generate dbt tests for a model
+> /generate-tests for models/staging/stg_orders.sql
+
+# Get a cost report for your Snowflake account
+> /cost-report
+```
+
+## Key Features
+
+All features are deterministic — they parse, trace, and measure. Not LLM pattern matching.
+
+### SQL Anti-Pattern Detection
+19 rules with confidence scoring — catches SELECT *, cartesian joins, non-sargable predicates, correlated subqueries, and more. **100% accuracy** on 1,077 benchmark queries.
+
+### Column-Level Lineage
+Automatic lineage extraction from SQL. Trace any column back through joins, CTEs, and subqueries to its source. Works standalone or with dbt manifests for project-wide lineage. **100% edge match** on 500 benchmark queries.
+
+### FinOps & Cost Analysis
+Credit analysis, expensive query detection, warehouse right-sizing, unused resource cleanup, and RBAC auditing.
+
+### Cross-Dialect Translation
+Transpile SQL between Snowflake, BigQuery, Databricks, Redshift, PostgreSQL, MySQL, SQL Server, and DuckDB.
+
+### PII Detection & Safety
+Automatic column scanning for PII across 15 categories with 30+ regex patterns. Safety checks and policy enforcement before query execution.
+
+### dbt Native
+Manifest parsing, test generation, model scaffolding, incremental model detection, and lineage-aware refactoring. 12 purpose-built skills including medallion patterns, yaml config generation, and dbt docs.
+
+### Data Visualization
+Interactive charts and dashboards from SQL results. The data-viz skill generates publication-ready visualizations with automatic chart type selection based on your data.
+
+### Local-First Tracing
+Built-in observability for AI interactions — trace tool calls, token usage, and session activity locally. No external services required. View traces with `altimate trace`.
+
+### AI Teammate Training
+Teach your AI teammate project-specific patterns, naming conventions, and best practices. The training system learns from examples and applies rules automatically across sessions.
+
+## Agent Modes
+
+Each agent has scoped permissions and purpose-built tools for its role.
+
+| Agent | Role | Access |
+|---|---|---|
+| **Builder** | Create dbt models, SQL pipelines, and data transformations | Full read/write |
+| **Analyst** | Explore data, run SELECT queries, and generate insights | Read-only enforced |
+| **Validator** | Data quality checks, schema validation, test coverage analysis | Read + validate |
+| **Migrator** | Cross-warehouse SQL translation, schema migration, dialect conversion | Read/write for migrations |
+| **Researcher** | Deep-dive analysis, documentation research, and knowledge extraction | Read-only |
+| **Trainer** | Teach project-specific patterns, naming conventions, and best practices | Read + write training data |
+| **Executive** | Business-audience summaries — translates findings into revenue, cost, and compliance impact | Read-only |
+
+> **New to altimate?** Start with **Analyst mode** — it's read-only and safe to run against production connections.
+
+## Supported Warehouses
+
+Snowflake · BigQuery · Databricks · PostgreSQL · Redshift · DuckDB · MySQL · SQL Server
+
+First-class support with schema indexing, query execution, and metadata introspection. SSH tunneling available for secure connections.
+
+## Works with Any LLM
+
+Model-agnostic — bring your own provider or run locally.
+
+Anthropic · OpenAI · Google Gemini · Google Vertex AI · Amazon Bedrock · Azure OpenAI · Mistral · Groq · DeepInfra · Cerebras · Cohere · Together AI · Perplexity · xAI · OpenRouter · Ollama · GitHub Copilot
+
+> **No API key?** **Codex** is a built-in provider with no key required. Select it via `/connect` to start immediately.
+
+## Skills
+
+altimate ships with built-in skills for every common data engineering task — type `/` in the TUI to browse available skills and get autocomplete. No memorization required.
+
+## Architecture
+
+```
+altimate (TypeScript CLI)
+        |
+   @altimateai/altimate-core (napi-rs → Rust)
+   SQL analysis, lineage, PII, safety — 45 functions, ~2ms per call
+        |
+   Native Node.js drivers
+   10 warehouses: Snowflake, BigQuery, PostgreSQL, Databricks,
+   Redshift, MySQL, SQL Server, Oracle, DuckDB, SQLite
+```
+
+The CLI handles AI interactions, TUI, and tool orchestration. SQL analysis is powered by the Rust-based `@altimateai/altimate-core` engine via napi-rs bindings (no Python required). Database connectivity uses native Node.js drivers with lazy loading.
+
+**No Python dependency**: All 73 tool methods run natively in TypeScript. No pip, venv, or Python installation needed.
+
+**dbt-first**: When working in a dbt project, the CLI automatically uses dbt's connection from `profiles.yml` — no separate warehouse configuration needed.
+
+### Monorepo structure
+
+```
+packages/
+  altimate-code/       TypeScript CLI (main entry point)
+  drivers/             Shared database drivers (10 warehouses)
+  dbt-tools/           dbt integration (TypeScript)
+  plugin/              Plugin system
+  sdk/                 SDKs (includes VS Code extension)
+  util/                Shared utilities
+```
+
+## Community & Contributing
+
+- **Slack**: [altimate.ai/slack](https://altimate.ai/slack) — Real-time chat for questions, showcases, and feature discussion
+- **Issues**: [GitHub Issues](https://github.com/AltimateAI/altimate-code/issues) — Bug reports and feature requests
+- **Discussions**: [GitHub Discussions](https://github.com/AltimateAI/altimate-code/discussions) — Long-form questions and proposals
+- **Security**: See [SECURITY.md](./SECURITY.md) for responsible disclosure
+
+Contributions welcome — docs, SQL rules, warehouse connectors, and TUI improvements are all needed. The contributing guide covers setup, the vouch system, and the issue-first PR policy.
+
+**[Read CONTRIBUTING.md →](./CONTRIBUTING.md)**
+
+## What's New
+
+- **v0.4.1** (March 2026) — env-based skill selection, session caching, tracing improvements
+- **v0.4.0** (Feb 2026) — data visualization skill, 99+ tools, training system
+- **v0.3.x** — [See full changelog →](CHANGELOG.md)
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+## Acknowledgements
+
+altimate is a fork of [OpenCode](https://github.com/anomalyco/opencode), the open-source AI coding agent. We build on top of their excellent foundation to add data-team-specific capabilities.

package/bin/altimate

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+
+const childProcess = require("child_process")
+const fs = require("fs")
+const path = require("path")
+const os = require("os")
+
+function run(target) {
+  const result = childProcess.spawnSync(target, process.argv.slice(2), {
+    stdio: "inherit",
+  })
+  if (result.error) {
+    console.error(result.error.message)
+    process.exit(1)
+  }
+  const code = typeof result.status === "number" ? result.status : 0
+  process.exit(code)
+}
+
+const envPath = process.env.ALTIMATE_CODE_BIN_PATH
+if (envPath) {
+  run(envPath)
+}
+
+const scriptPath = fs.realpathSync(__filename)
+const scriptDir = path.dirname(scriptPath)
+
+//
+const cached = path.join(scriptDir, ".altimate-code")
+if (fs.existsSync(cached)) {
+  run(cached)
+}
+
+const platformMap = {
+  darwin: "darwin",
+  linux: "linux",
+  win32: "windows",
+}
+const archMap = {
+  x64: "x64",
+  arm64: "arm64",
+  arm: "arm",
+}
+
+let platform = platformMap[os.platform()]
+if (!platform) {
+  platform = os.platform()
+}
+let arch = archMap[os.arch()]
+if (!arch) {
+  arch = os.arch()
+}
+const scope = "@altimateai"
+const base = "altimate-code-" + platform + "-" + arch
+const binary = platform === "windows" ? "altimate-code.exe" : "altimate-code"
+
+function supportsAvx2() {
+  if (arch !== "x64") return false
+
+  if (platform === "linux") {
+    try {
+      return /(^|\s)avx2(\s|$)/i.test(fs.readFileSync("/proc/cpuinfo", "utf8"))
+    } catch {
+      return false
+    }
+  }
+
+  if (platform === "darwin") {
+    try {
+      const result = childProcess.spawnSync("sysctl", ["-n", "hw.optional.avx2_0"], {
+        encoding: "utf8",
+        timeout: 1500,
+      })
+      if (result.status !== 0) return false
+      return (result.stdout || "").trim() === "1"
+    } catch {
+      return false
+    }
+  }
+
+  if (platform === "windows") {
+    const cmd =
+      '(Add-Type -MemberDefinition "[DllImport(""kernel32.dll"")] public static extern bool IsProcessorFeaturePresent(int ProcessorFeature);" -Name Kernel32 -Namespace Win32 -PassThru)::IsProcessorFeaturePresent(40)'
+
+    for (const exe of ["powershell.exe", "pwsh.exe", "pwsh", "powershell"]) {
+      try {
+        const result = childProcess.spawnSync(exe, ["-NoProfile", "-NonInteractive", "-Command", cmd], {
+          encoding: "utf8",
+          timeout: 3000,
+          windowsHide: true,
+        })
+        if (result.status !== 0) continue
+        const out = (result.stdout || "").trim().toLowerCase()
+        if (out === "true" || out === "1") return true
+        if (out === "false" || out === "0") return false
+      } catch {
+        continue
+      }
+    }
+
+    return false
+  }
+
+  return false
+}
+
+const names = (() => {
+  const avx2 = supportsAvx2()
+  const baseline = arch === "x64" && !avx2
+
+  if (platform === "linux") {
+    const musl = (() => {
+      try {
+        if (fs.existsSync("/etc/alpine-release")) return true
+      } catch {
+        // ignore
+      }
+
+      try {
+        const result = childProcess.spawnSync("ldd", ["--version"], { encoding: "utf8" })
+        const text = ((result.stdout || "") + (result.stderr || "")).toLowerCase()
+        if (text.includes("musl")) return true
+      } catch {
+        // ignore
+      }
+
+      return false
+    })()
+
+    if (musl) {
+      if (arch === "x64") {
+        if (baseline) return [`${base}-baseline-musl`, `${base}-musl`, `${base}-baseline`, base]
+        return [`${base}-musl`, `${base}-baseline-musl`, base, `${base}-baseline`]
+      }
+      return [`${base}-musl`, base]
+    }
+
+    if (arch === "x64") {
+      if (baseline) return [`${base}-baseline`, base, `${base}-baseline-musl`, `${base}-musl`]
+      return [base, `${base}-baseline`, `${base}-musl`, `${base}-baseline-musl`]
+    }
+    return [base, `${base}-musl`]
+  }
+
+  if (arch === "x64") {
+    if (baseline) return [`${base}-baseline`, base]
+    return [base, `${base}-baseline`]
+  }
+  return [base]
+})()
+
+function findBinary(startDir) {
+  let current = startDir
+  for (;;) {
+    const modules = path.join(current, "node_modules")
+    if (fs.existsSync(modules)) {
+      for (const name of names) {
+        const candidate = path.join(modules, scope, name, "bin", binary)
+        if (fs.existsSync(candidate)) return candidate
+      }
+    }
+    const parent = path.dirname(current)
+    if (parent === current) {
+      return
+    }
+    current = parent
+  }
+}
+
+const resolved = findBinary(scriptDir)
+if (!resolved) {
+  console.error(
+    "It seems that your package manager failed to install the right version of the altimate-code CLI for your platform. You can try manually installing " +
+      names.map((n) => `\"${scope}/${n}\"`).join(" or ") +
+      " package",
+  )
+  process.exit(1)
+}
+
+run(resolved)

package/bin/altimate-code

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+
+const childProcess = require("child_process")
+const fs = require("fs")
+const path = require("path")
+const os = require("os")
+
+function run(target) {
+  const result = childProcess.spawnSync(target, process.argv.slice(2), {
+    stdio: "inherit",
+  })
+  if (result.error) {
+    console.error(result.error.message)
+    process.exit(1)
+  }
+  const code = typeof result.status === "number" ? result.status : 0
+  process.exit(code)
+}
+
+const envPath = process.env.ALTIMATE_CODE_BIN_PATH
+if (envPath) {
+  run(envPath)
+}
+
+const scriptPath = fs.realpathSync(__filename)
+const scriptDir = path.dirname(scriptPath)
+
+//
+const cached = path.join(scriptDir, ".altimate-code")
+if (fs.existsSync(cached)) {
+  run(cached)
+}
+
+const platformMap = {
+  darwin: "darwin",
+  linux: "linux",
+  win32: "windows",
+}
+const archMap = {
+  x64: "x64",
+  arm64: "arm64",
+  arm: "arm",
+}
+
+let platform = platformMap[os.platform()]
+if (!platform) {
+  platform = os.platform()
+}
+let arch = archMap[os.arch()]
+if (!arch) {
+  arch = os.arch()
+}
+const scope = "@altimateai"
+const base = "altimate-code-" + platform + "-" + arch
+const binary = platform === "windows" ? "altimate-code.exe" : "altimate-code"
+
+function supportsAvx2() {
+  if (arch !== "x64") return false
+
+  if (platform === "linux") {
+    try {
+      return /(^|\s)avx2(\s|$)/i.test(fs.readFileSync("/proc/cpuinfo", "utf8"))
+    } catch {
+      return false
+    }
+  }
+
+  if (platform === "darwin") {
+    try {
+      const result = childProcess.spawnSync("sysctl", ["-n", "hw.optional.avx2_0"], {
+        encoding: "utf8",
+        timeout: 1500,
+      })
+      if (result.status !== 0) return false
+      return (result.stdout || "").trim() === "1"
+    } catch {
+      return false
+    }
+  }
+
+  if (platform === "windows") {
+    const cmd =
+      '(Add-Type -MemberDefinition "[DllImport(""kernel32.dll"")] public static extern bool IsProcessorFeaturePresent(int ProcessorFeature);" -Name Kernel32 -Namespace Win32 -PassThru)::IsProcessorFeaturePresent(40)'
+
+    for (const exe of ["powershell.exe", "pwsh.exe", "pwsh", "powershell"]) {
+      try {
+        const result = childProcess.spawnSync(exe, ["-NoProfile", "-NonInteractive", "-Command", cmd], {
+          encoding: "utf8",
+          timeout: 3000,
+          windowsHide: true,
+        })
+        if (result.status !== 0) continue
+        const out = (result.stdout || "").trim().toLowerCase()
+        if (out === "true" || out === "1") return true
+        if (out === "false" || out === "0") return false
+      } catch {
+        continue
+      }
+    }
+
+    return false
+  }
+
+  return false
+}
+
+const names = (() => {
+  const avx2 = supportsAvx2()
+  const baseline = arch === "x64" && !avx2
+
+  if (platform === "linux") {
+    const musl = (() => {
+      try {
+        if (fs.existsSync("/etc/alpine-release")) return true
+      } catch {
+        // ignore
+      }
+
+      try {
+        const result = childProcess.spawnSync("ldd", ["--version"], { encoding: "utf8" })
+        const text = ((result.stdout || "") + (result.stderr || "")).toLowerCase()
+        if (text.includes("musl")) return true
+      } catch {
+        // ignore
+      }
+
+      return false
+    })()
+
+    if (musl) {
+      if (arch === "x64") {
+        if (baseline) return [`${base}-baseline-musl`, `${base}-musl`, `${base}-baseline`, base]
+        return [`${base}-musl`, `${base}-baseline-musl`, base, `${base}-baseline`]
+      }
+      return [`${base}-musl`, base]
+    }
+
+    if (arch === "x64") {
+      if (baseline) return [`${base}-baseline`, base, `${base}-baseline-musl`, `${base}-musl`]
+      return [base, `${base}-baseline`, `${base}-musl`, `${base}-baseline-musl`]
+    }
+    return [base, `${base}-musl`]
+  }
+
+  if (arch === "x64") {
+    if (baseline) return [`${base}-baseline`, base]
+    return [base, `${base}-baseline`]
+  }
+  return [base]
+})()
+
+function findBinary(startDir) {
+  let current = startDir
+  for (;;) {
+    const modules = path.join(current, "node_modules")
+    if (fs.existsSync(modules)) {
+      for (const name of names) {
+        const candidate = path.join(modules, scope, name, "bin", binary)
+        if (fs.existsSync(candidate)) return candidate
+      }
+    }
+    const parent = path.dirname(current)
+    if (parent === current) {
+      return
+    }
+    current = parent
+  }
+}
+
+const resolved = findBinary(scriptDir)
+if (!resolved) {
+  console.error(
+    "It seems that your package manager failed to install the right version of the altimate-code CLI for your platform. You can try manually installing " +
+      names.map((n) => `\"${scope}/${n}\"`).join(" or ") +
+      " package",
+  )
+  process.exit(1)
+}
+
+run(resolved)

package/package.json

@@ -1,10 +1,33 @@
 {
   "name": "altimate-code",
-  "version": "0.0.1",
-  "description": "The data engineering agent for dbt, SQL, and cloud warehouses.",
-  "license": "MIT",
+  "description": "The AI-native data engineering agent for the terminal",
   "repository": {
     "type": "git",
-    "url": "https://github.com/AltimateAI/altimate-code"
+    "url": "git+https://github.com/AltimateAI/altimate-code.git"
+  },
+  "homepage": "https://github.com/AltimateAI/altimate-code#readme",
+  "bugs": "https://github.com/AltimateAI/altimate-code/issues",
+  "bin": {
+    "altimate": "./bin/altimate",
+    "altimate-code": "./bin/altimate-code"
+  },
+  "scripts": {
+    "postinstall": "bun ./postinstall.mjs || node ./postinstall.mjs"
+  },
+  "version": "v0.4.7",
+  "license": "MIT",
+  "optionalDependencies": {
+    "@altimateai/altimate-code-linux-x64": "v0.4.7",
+    "@altimateai/altimate-code-windows-arm64": "v0.4.7",
+    "@altimateai/altimate-code-linux-arm64-musl": "v0.4.7",
+    "@altimateai/altimate-code-darwin-x64": "v0.4.7",
+    "@altimateai/altimate-code-windows-x64": "v0.4.7",
+    "@altimateai/altimate-code-linux-x64-musl": "v0.4.7",
+    "@altimateai/altimate-code-darwin-x64-baseline": "v0.4.7",
+    "@altimateai/altimate-code-linux-x64-baseline-musl": "v0.4.7",
+    "@altimateai/altimate-code-linux-x64-baseline": "v0.4.7",
+    "@altimateai/altimate-code-linux-arm64": "v0.4.7",
+    "@altimateai/altimate-code-darwin-arm64": "v0.4.7",
+    "@altimateai/altimate-code-windows-x64-baseline": "v0.4.7"
   }
-}
+}

package/postinstall.mjs

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+
+import fs from "fs"
+import path from "path"
+import os from "os"
+import { fileURLToPath } from "url"
+import { createRequire } from "module"
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const require = createRequire(import.meta.url)
+
+function detectPlatformAndArch() {
+  // Map platform names
+  let platform
+  switch (os.platform()) {
+    case "darwin":
+      platform = "darwin"
+      break
+    case "linux":
+      platform = "linux"
+      break
+    case "win32":
+      platform = "windows"
+      break
+    default:
+      platform = os.platform()
+      break
+  }
+
+  // Map architecture names
+  let arch
+  switch (os.arch()) {
+    case "x64":
+      arch = "x64"
+      break
+    case "arm64":
+      arch = "arm64"
+      break
+    case "arm":
+      arch = "arm"
+      break
+    default:
+      arch = os.arch()
+      break
+  }
+
+  return { platform, arch }
+}
+
+function findBinary() {
+  const { platform, arch } = detectPlatformAndArch()
+  const packageName = `@altimateai/altimate-code-${platform}-${arch}`
+  const binaryName = platform === "windows" ? "altimate-code.exe" : "altimate-code"
+
+  try {
+    // Use require.resolve to find the package
+    const packageJsonPath = require.resolve(`${packageName}/package.json`)
+    const packageDir = path.dirname(packageJsonPath)
+    const binaryPath = path.join(packageDir, "bin", binaryName)
+
+    if (!fs.existsSync(binaryPath)) {
+      throw new Error(`Binary not found at ${binaryPath}`)
+    }
+
+    return { binaryPath, binaryName }
+  } catch (error) {
+    throw new Error(`Could not find package ${packageName}: ${error.message}`)
+  }
+}
+
+function prepareBinDirectory(binaryName) {
+  const binDir = path.join(__dirname, "bin")
+  const targetPath = path.join(binDir, binaryName)
+
+  // Ensure bin directory exists
+  if (!fs.existsSync(binDir)) {
+    fs.mkdirSync(binDir, { recursive: true })
+  }
+
+  // Remove existing binary/symlink if it exists
+  if (fs.existsSync(targetPath)) {
+    fs.unlinkSync(targetPath)
+  }
+
+  return { binDir, targetPath }
+}
+
+function printWelcome(version) {
+  const cleanVersion = version.replace(/^v/, "")
+  const v = `altimate-code v${cleanVersion} installed`
+  const lines = [
+    "",
+    "  Get started:",
+    "    altimate              Open the TUI",
+    '    altimate run "hello"  Run a quick task',
+    "    altimate --help       See all commands",
+    "",
+    "  Docs: https://altimate-code.dev",
+    "",
+  ]
+  // Box width: pad all lines to the same length
+  const contentWidth = Math.max(v.length, ...lines.map((l) => l.length)) + 2
+  const pad = (s) => s + " ".repeat(contentWidth - s.length)
+  const top = `  ╭${"─".repeat(contentWidth + 2)}╮`
+  const bot = `  ╰${"─".repeat(contentWidth + 2)}╯`
+  const empty = `  │ ${" ".repeat(contentWidth)} │`
+  const row = (s) => `  │ ${pad(s)} │`
+
+  // Use stderr — npm v7+ silences postinstall stdout
+  const out = (s) => process.stderr.write(s + "\n")
+  out(top)
+  out(empty)
+  out(row(` ${v}`))
+  for (const line of lines) out(row(line))
+  out(bot)
+}
+
+/**
+ * Write a marker file so the CLI can show a welcome/upgrade banner on first run.
+ * npm v7+ silences postinstall stdout, so the CLI reads this marker at startup instead.
+ */
+function writeUpgradeMarker(version) {
+  try {
+    const xdgData = process.env.XDG_DATA_HOME || path.join(os.homedir(), ".local", "share")
+    const dataDir = path.join(xdgData, "altimate-code")
+    fs.mkdirSync(dataDir, { recursive: true })
+    fs.writeFileSync(path.join(dataDir, ".installed-version"), version.replace(/^v/, ""))
+  } catch {
+    // Non-fatal — the CLI just won't show a welcome banner
+  }
+}
+
+async function main() {
+  let version
+  try {
+    const pkgPath = path.join(__dirname, "package.json")
+    if (fs.existsSync(pkgPath)) {
+      version = JSON.parse(fs.readFileSync(pkgPath, "utf-8")).version
+    }
+  } catch {}
+
+  try {
+    if (os.platform() === "win32") {
+      // On Windows, the .exe is already included in the package and bin field points to it
+      // No postinstall setup needed
+      if (version) writeUpgradeMarker(version)
+      return
+    }
+
+    // On non-Windows platforms, just verify the binary package exists
+    // Don't replace the wrapper script - it handles binary execution
+    const { binaryPath } = findBinary()
+    const target = path.join(__dirname, "bin", ".altimate-code")
+    if (fs.existsSync(target)) fs.unlinkSync(target)
+    try {
+      fs.linkSync(binaryPath, target)
+    } catch {
+      fs.copyFileSync(binaryPath, target)
+    }
+    fs.chmodSync(target, 0o755)
+    // Write marker only — npm v7+ suppresses all postinstall output.
+    // The CLI picks up the marker and shows the welcome box on first run.
+    if (version) writeUpgradeMarker(version)
+  } catch (error) {
+    console.error("Failed to setup altimate-code binary:", error.message)
+    process.exit(1)
+  }
+}
+
+try {
+  main()
+} catch (error) {
+  console.error("Postinstall script error:", error.message)
+  process.exit(0)
+}