code-hq

Project knowledge graph for agentic development

code-hq is a local-first knowledge graph CLI and library for managing project context, tasks, notes, and relationships using semantic JSON-LD. Perfect for AI agents and human developers working together.

✨ Features

🎯 Task Management

• Create and track tasks with rich metadata (status, priority, assignees, estimates)
• Time tracking with start/stop timers and session logging
• Professional timesheet reporting (CSV, JSON, table formats)
• Dependency tracking and milestone management
• Custom tags and file associations

⏱️ Time Tracking & Timesheets

• Built-in timer system for accurate time logging
• Generate professional timesheets with required schema: date, project, issueId, hours, description
• Filter by date range, assignee, and project
• Export to CSV for invoicing and reporting
• Automatic hour calculation from time sessions

📝 Knowledge Management

• Notes, people, milestones, and custom entity types
• Semantic relationships between entities
• Full-text search and query capabilities
• Markdown support for rich content

🔍 Powerful Querying

• SPARQL-like query language (TQL)
• Filter, sort, and aggregate data
• Export results to JSON, CSV, or Markdown

🤖 AI-Agent Friendly

• JSON-LD format for semantic understanding
• Comprehensive prompts and workflows for AI assistants
• VSCode extension for visual management

📦 Installation

# Global installation (recommended)
npm install -g code-hq

# Or use with npx
npx code-hq init

# Local installation
npm install code-hq

🚀 Quick Start

# Initialize a new project
code-hq init

# Create a task
code-hq create task "Implement login feature" \
  --status todo \
  --priority high \
  --estimated-hours 8 \
  --tags "auth,frontend"

# Start time tracking
code-hq start task:1

# Stop timer and log hours
code-hq stop task:1

# Generate timesheet report
code-hq timesheet --from 7d --format csv

# List all tasks
code-hq list tasks

# Query with filters
code-hq query "status=in-progress priority=high"

# Create a note
code-hq create note "Architecture decisions" \
  --content "Using microservices pattern..." \
  --tags "architecture,docs"

⏱️ Timesheet Reporting

Generate professional timesheets for invoicing and reporting:

# Generate weekly timesheet
code-hq timesheet --from 7d

# Export to CSV with date range
code-hq timesheet \
  --from 2024-11-01 \
  --to 2024-11-15 \
  --format csv \
  --output timesheet.csv

# Filter by project and assignee
code-hq timesheet \
  --project "ACME Corp" \
  --assignee @alice \
  --from 1m

# View as formatted table
code-hq timesheet --from 2w --format table

Timesheet Output Schema

Standard format for all timesheet exports:

• date: ISO 8601 date of work session
• project: Project name from task tags
• issueId: Task identifier
• hours: Decimal hours worked
• description: Task title/description

📚 Core Commands

Entity Management

# Create entities
code-hq create task "Task title" [options]
code-hq create note "Note title" [options]
code-hq create person "Name" [options]
code-hq create milestone "Milestone name" [options]

# List entities
code-hq list tasks [--status <status>] [--assignee <person>]
code-hq list notes [--tags <tags>]
code-hq list people
code-hq list milestones

# Update entities
code-hq update <entity-id> [options]

# Delete entities
code-hq delete <entity-id>

Time Tracking

# Start timer
code-hq start <task-id> [--description "What I'm working on"]

# Stop timer
code-hq stop <task-id>

# View time details
code-hq time <task-id>

# Check active timers
code-hq status

Timesheet Commands

# Generate timesheet
code-hq timesheet [options]
  --from <date>          # Start date (ISO 8601 or relative: "7d", "2w", "1m")
  --to <date>            # End date (defaults to today)
  --assignee <person>    # Filter by assignee
  --project <name>       # Filter/override project name
  --format <type>        # Output format: table|csv|json (default: table)
  --output <file>        # Write to file instead of stdout

Querying

# Simple filters
code-hq query "status=done priority=high"

# Complex queries with TQL
code-hq query --tql query.tql

# Export results
code-hq query "tags=frontend" --format json > results.json

🏗️ Project Structure

.code-hq/
├── graph.jsonld        # Main knowledge graph
├── config.json         # Project configuration
└── queries/           # Saved queries

🎨 VSCode Extension

Install the companion VSCode extension for visual project management:

• Kanban boards
• Timeline views
• Calendar integration
• Interactive timesheet view with filtering and CSV export
• Task details and notes editor
• Graph visualization

Search for "CodeHQ" in VSCode marketplace or install from Open VSX.

📖 Documentation

• Task Management Guide
• Timesheet Workflows
• Query Examples
• AI Agent Integration

🤝 AI Integration

code-hq is designed to work seamlessly with AI coding assistants:

• Windsurf workflows: Pre-built workflows for common tasks
• Agent prompts: Comprehensive guides in .code-hq/prompts/
• Semantic structure: JSON-LD format for AI understanding
• Query templates: Example queries for AI agents

🔧 Configuration

{
  "projectName": "My Project",
  "defaultAssignee": "@me",
  "defaultPriority": "medium",
  "timeTracking": {
    "enabled": true,
    "roundTo": 0.25
  }
}

🛠️ Development

# Clone the repository
git clone https://github.com/trentbrew/code-hq.git
cd code-hq/core

# Install dependencies
bun install

# Run tests
bun test

# Build
bun run build

# Link for local development
npm link

📊 Example Workflow

# Start your day
code-hq create task "Fix bug #123" --priority high --estimated-hours 2
code-hq start task:1

# Work on the task...
# (timer running in background)

# Take a break
code-hq stop task:1

# Resume later
code-hq start task:1 --description "Adding tests"
code-hq stop task:1

# End of day - check your time
code-hq time task:1

# End of week - generate timesheet
code-hq timesheet --from 7d --format csv --output week-47.csv

🎯 Use Cases

• Freelancers: Track billable hours and generate invoices
• Teams: Coordinate work across multiple projects
• AI Development: Provide rich context for coding assistants
• Project Management: Maintain single source of truth
• Knowledge Management: Document decisions and relationships

🗺️ Roadmap

• [x] Core CLI and graph management
• [x] Task and time tracking
• [x] Timesheet reporting system
• [x] VSCode extension
• [ ] GitHub integration
• [ ] Cloud sync (optional)
• [ ] Team collaboration features
• [ ] Advanced analytics

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

📄 License

MIT © Trent Brew

🔗 Links

• GitHub Repository
• VSCode Extension
• Issue Tracker
• Changelog

💬 Support

• 📧 Email: [email protected]
• 💬 Discussions: GitHub Discussions
• 🐛 Issues: GitHub Issues

Built with ❤️ for developers and AI agents working together