code-hq is a project-scoped knowledge graph system designed for agentic development workflows. It combines TQL's powerful EAV query engine with opinionated conventions for project management, creating a semantic memory layer that both humans and AI agents can read, write, and reason over.
Core Principle: Every project gets a .code-hq/ directory containing a semantic graph of tasks, notes, people, milestones, and custom entitiesβqueryable via CLI, manipulated by AI agents, and visualizable in rich UIs.
# Install dependencies
bun install
# Initialize code-hq in your project
bun run code-hq init
# Create your first task
bun run code-hq create task "Setup authentication" --priority high --status in-progress
# List all tasks
bun run code-hq tasks
# Show kanban board
bun run code-hq show --view kanban
# Create a note
bun run code-hq create note "Architecture Decision" --note-type decision --content "Using PostgreSQL"
# Validate your graph
bun run code-hq validatecode-hq transforms your project into an intelligent knowledge graph:
- π Local-First: Data lives in
.code-hq/alongside your code - π§ Agent-Native: Built for AI agents to read, write, and reason over project state
- π Queryable: Powerful EQL-S queries + natural language
- π Visual: Rich views (kanban, calendar, graph, tables)
- π Semantic: JSON-LD format with relationships between entities
Built on TQL
code-hq is powered by TQL (Tree Query Language), a schema-agnostic EAV engine with Datalog evaluation. TQL provides the query engine, while code-hq adds project management conventions and rich UIs.
βββ src/
β βββ eav-engine.ts # Facts store, flattening, index maintenance
β βββ query/ # EQL-S parser, Datalog evaluator, generators
β βββ cli/ # TQL CLI entrypoint + helpers
β βββ ai/ # Natural language orchestrator & providers
β βββ graph/ # Agent graph runtime, validators, executors
β βββ analytics/ # Dataset insights, relationship mining
β βββ adapters/ # Integrations for workflows & tools
β βββ telemetry.ts # Diagnostics + tracing hooks
β βββ index.ts # Public bundler-friendly exports
βββ examples/ # End-to-end demos and playground scripts
βββ docs/ # Deep-dive documentation
βββ data/ # Sample datasets for demos and tests
βββ test/ # Vitest suites (projection, workflows, etc.)
- Schema agnostic ingestion β Any JSON becomes
attr(e,a,v)facts with dot-path attributes and link support. - Datalog + EQL-S β Semi-naive evaluator with projections, filters, regex, math, date ops, and ordering.
- TQL CLI β
bun run tqlto load local/remote data, run EQL-S, or translate natural language with--nl. - NL orchestrator β
src/ai/routes natural-language prompts to structured queries with optional tool calls. - Agent graph runtime β Deterministic node/edge engine for complex LLM workflows with budgets and tracing.
- Analytics toolkit β Relationship analysis, schema inference, and dataset introspection helpers.
import { EAVStore, jsonEntityFacts } from './src/index.js';
const store = new EAVStore();
const jsonData = {
id: 1,
title: 'Hello World',
tags: ['demo', 'example'],
metrics: { views: 100 },
};
store.addFacts(jsonEntityFacts('post:1', jsonData, 'post'));
const titles = store.getFactsByAttribute('title');
console.log(titles);bun run tql \
-d https://jsonplaceholder.typicode.com/users \
-q "FIND user AS ?u RETURN ?u.id, ?u.email"
# With natural language translation
bun run tql -d data/posts.json -q "posts with >1000 views" --nl# Type checking
bun run typecheck
# Build distributable bundle
bun run build
# Run Vitest suites
bun run test
# Clean build artifacts
bun run clean- EAV Engine Guide
- Workflows & Agent Graphs
- Tree-of-Thought Planner
- Analytics toolkit overview
- Examples directory for runnable scripts and demos
Built with Bun for fast TypeScript execution.
- β CLI tool
- β Local storage
- β Entity schemas
- β Query language
- β Basic VSCode extension
- π Cloud sync & backup
- π Web dashboard
- π₯ Team collaboration
- π Advanced analytics
- π’ Enterprise SSO
code-hq core will always be free and open source. Premium features help us sustain development.