{"id":50817178,"url":"https://github.com/abhirockzz/cosmosdb-copilot-sdk-time-tracker","last_synced_at":"2026-06-13T10:33:10.850Z","repository":{"id":340800734,"uuid":"1165360932","full_name":"abhirockzz/cosmosdb-copilot-sdk-time-tracker","owner":"abhirockzz","description":"TimeTrack — Built with the GitHub Copilot SDK and Azure Cosmos DB","archived":false,"fork":false,"pushed_at":"2026-02-26T15:09:44.000Z","size":1573,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-26T21:07:12.987Z","etag":null,"topics":["github-copilot-sdk","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/abhirockzz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-24T04:49:40.000Z","updated_at":"2026-02-26T15:11:15.000Z","dependencies_parsed_at":null,"dependency_job_id":"7d9224fd-610b-42d0-a13f-a438ee0ff67f","html_url":"https://github.com/abhirockzz/cosmosdb-copilot-sdk-time-tracker","commit_stats":null,"previous_names":["abhirockzz/cosmosdb-copilot-sdk-time-tracker"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/abhirockzz/cosmosdb-copilot-sdk-time-tracker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abhirockzz%2Fcosmosdb-copilot-sdk-time-tracker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abhirockzz%2Fcosmosdb-copilot-sdk-time-tracker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abhirockzz%2Fcosmosdb-copilot-sdk-time-tracker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abhirockzz%2Fcosmosdb-copilot-sdk-time-tracker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/abhirockzz","download_url":"https://codeload.github.com/abhirockzz/cosmosdb-copilot-sdk-time-tracker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abhirockzz%2Fcosmosdb-copilot-sdk-time-tracker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34281700,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["github-copilot-sdk","typescript"],"created_at":"2026-06-13T10:33:09.636Z","updated_at":"2026-06-13T10:33:10.836Z","avatar_url":"https://github.com/abhirockzz.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"#  TimeTrack — Built with the GitHub Copilot SDK and Azure Cosmos DB\n\nThe [GitHub Copilot SDK](https://github.com/github/copilot-sdk) lets you embed Copilot's agentic workflows directly into your apps and it's available for Python, TypeScript, Go, and .NET.\n\n**TimeTrack** is simple desktop app built with the GitHub Copilot SDK (TypeScript) and [Azure Cosmos DB](https://learn.microsoft.com/en-us/azure/cosmos-db/introduction).\n\nYou can:\n\n- Track time with a start/stop timer, projects, and tags\n- View entries, reports, and charts across multiple users\n- Ask natural language questions about your time data — Copilot generates and runs Cosmos DB SQL queries automatically\n- Seed realistic sample data to explore the app immediately\n\n\u003ca href=\"https://abhirockzz.github.io/videos/timetrack_app_demo.mp4\" target=\"_blank\"\u003e\n  \u003cimg src=\"images/report_and_query.png\" alt=\"Quick demo\" width=\"100%\"\u003e\n\u003c/a\u003e\n\n## Highlights\n\n- **🔧 Tool calling with Copilot SDK** — The app uses the SDK's [`defineTool`](https://github.com/github/copilot-sdk/tree/main/nodejs#tools) API to register a database query tool that the AI calls autonomously. When a user asks a question in plain English, the SDK reasons about it, generates a Cosmos DB SQL query, executes it via the tool, and returns a conversational answer.\n\n- **🔑 BYOK (Bring Your Own Key)** — The Copilot SDK's [BYOK](https://github.com/github/copilot-sdk/blob/main/docs/guides/setup/byok.md) support lets you swap the default Copilot model for your own deployment. This app supports Azure AI Foundry and local OpenAI-compatible servers (Ollama, Foundry Local) — just configure a few env vars and the app behavior stays identical.\n\n- **💻 Local mode** — You can run the app without an Azure account by using the [Cosmos DB vNext emulator](https://learn.microsoft.com/en-us/azure/cosmos-db/emulator-linux). It runs as a single Docker container with HTTP (no TLS setup) and includes a built-in Data Explorer UI at `http://localhost:1234` for browsing your data.\n\n## Prerequisites\n\n1. [Node.js 22+](https://nodejs.org/) (system-installed, required by the Copilot CLI)\n2. **GitHub Copilot CLI** — [install it](https://docs.github.com/en/copilot/how-tos/set-up/install-copilot-cli) and login\n3. **One of the following for Cosmos DB:**\n   - **Azure**: Azure CLI + Azure Cosmos DB account\n   - **Run locally**: [Cosmos DB vNext emulator](https://learn.microsoft.com/en-us/azure/cosmos-db/emulator-linux) (Docker)\n\n## Clone the Repository\n\n```bash\ngit clone https://github.com/abhirockzz/cosmosdb-copilot-sdk-time-tracker.git\n\ncd cosmosdb-copilot-sdk-time-tracker\n\nnpm install\n```\n\n---\n\n## Option A: Using Azure Cosmos DB\n\n### 1. Create Cosmos DB Resources\n\n```bash\naz login\n\nexport RG_NAME=\"timetracker-rg\"\nexport COSMOS_ACCOUNT=\"timetracker-cosmos\"\nexport LOCATION=\"westus2\"\n\naz group create --name $RG_NAME --location $LOCATION\n\naz cosmosdb create \\\n  --name $COSMOS_ACCOUNT \\\n  --resource-group $RG_NAME \\\n  --kind GlobalDocumentDB\n\naz cosmosdb sql database create \\\n  --account-name $COSMOS_ACCOUNT \\\n  --resource-group $RG_NAME \\\n  --name timetracker\n\naz cosmosdb sql container create \\\n  --account-name $COSMOS_ACCOUNT \\\n  --resource-group $RG_NAME \\\n  --database-name timetracker \\\n  --name timeEntries \\\n  --partition-key-path /userId\n```\n\n### 2. Assign RBAC Role\n\n```bash\nUSER_ID=$(az ad signed-in-user show --query id -o tsv)\nCOSMOS_ID=$(az cosmosdb show --name $COSMOS_ACCOUNT --resource-group $RG_NAME --query id -o tsv)\n\naz cosmosdb sql role assignment create \\\n  --account-name $COSMOS_ACCOUNT \\\n  --resource-group $RG_NAME \\\n  --role-definition-name \"Cosmos DB Built-in Data Contributor\" \\\n  --principal-id $USER_ID \\\n  --scope $COSMOS_ID\n```\n\n### 3. Run the App\n\n```bash\ncp .env.example .env\n# Edit .env — set COSMOS_ACCOUNT to your account endpoint\n\nnpm start\n```\n\nSkip to [Use the App](#use-the-app) section below.\n\n---\n\n## Option B: Using the Cosmos DB vNext Emulator\n\nThe vNext emulator [runs on Linux/macOS/Windows via Docker](https://learn.microsoft.com/en-us/azure/cosmos-db/emulator-linux) without the need for an Azure account.\n\n### 1. Start the Emulator\n\n```bash\ndocker run -p 8081:8081 -p 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview\n```\n\n### 2. Create Database and Container\n\nOpen the Data Explorer at http://localhost:1234 and create:\n\n- Database: `timetracker`\n- Container: `timeEntries` with partition key `/userId`\n\n### 3. Run the App\n\n```bash\ncp .env.example .env\n```\n\nSet `USE_EMULATOR=true` in your `.env`:\n\n```bash\nUSE_EMULATOR=true\nnpm install\nnpm start\n# COSMOS_ACCOUNT is not needed when using the emulator\n```\n\n---\n\n## Use the App\n\n**Login** — Select a user (alice, bob, or carol) or enter the name of a custom user\n\n![](images/login.png)\n\n\u003e This is simply to simulate multiple users in the app. There is no authentication or security — all data is stored in the same Cosmos DB container and scoped by `userId`.\n\n**Load sample data** — Click \"Load sample data\" on first login to seed activity data for the user.\n\n![](images/load_sample_data.png)\n\n**Track time** — Start/stop a timer with project and tag selection\n\n![](images/track.png)\n\n**Ask questions** — Use the AI chat to query your time data in natural language. The AI generates Cosmos DB SQL behind the scenes, so you can ask things that go well beyond the fixed reports:\n\n- *Do I tend to work longer hours early in the week or late in the week?*\n- *How does my Monday workload compare to my Friday workload?*\n- *Compare my total hours this week vs last week*\n- *Which single task consumed the most total time across all days?*\n- *Rank my projects by total hours and show the percentage each represents*\n- *Summarize my last two weeks in 3 bullet points*\n\n**View reports** — Charts and summaries for Today, Yesterday, This Week, Last Week\n\n---\n\n## How It Works\n\nThe user's question flows from the Electron UI through the Copilot SDK to the model, which generates a Cosmos DB SQL query, executes it via a tool call, and either returns a conversational answer or self-corrects and retries if the SQL errors out.\n\n```\n+--------------+     +----------------+     +-------------+\n|  Electron UI | --\u003e |  Copilot SDK   | --\u003e | Copilot CLI |\n|  (renderer)  |     |  (main process)|     |  (sidecar)  |\n+--------------+     +----------------+     +------+------+\n       ^                                           |\n       |                                    tool call: query_time_data\n       |                                           |\n       |                                    +------v------+\n       |                                    |  Cosmos DB  |\n       |                                    +------+------+\n       |                                           |\n       |                                     result or error\n       |                                           |\n       |                                    +------v------+\n       |                                    |    Model    |\n       |                                    | (interpret) |\n       |                                    +------+------+\n       |                                      |         |\n       |                                success?     SQL error?\n       |                                   |          retry with\n       |                                   |        corrected SQL\n       |                                   |             |\n       +---  AI response  \u003c---------------+     (back to Cosmos DB)\n```\n\n### AI-Generated SQL Queries\n\nWhen you ask a natural language question like *\"how productive was I this week?\"*, the app uses the Copilot SDK's `defineTool` API to let the AI generate and execute Cosmos DB SQL queries:\n\n```typescript\nconst queryTool = defineTool(\"query_time_data\", {\n  description: \"Execute a read-only Cosmos DB SQL query...\",\n  parameters: z.object({\n    query: z.string().describe(\"Cosmos DB SQL query\"),\n  }),\n  handler: async ({ query }) =\u003e {\n    const result = await runQuery(userId, query);\n    return JSON.stringify(result);\n  },\n});\n\nsession = await client.createSession({\n  tools: [queryTool],\n  systemMessage: { mode: \"replace\", content: \"...\" },\n});\n```\n\nThe AI translates intent into SQL, runs it against your data (scoped to the current user's partition key), and summarizes the results conversationally. If the generated SQL hits a Cosmos DB error (e.g., unsupported syntax like `ORDER BY` on an aggregate alias), the error is returned to the model, which self-corrects and retries with fixed SQL — typically succeeding within 1–2 attempts, with no user intervention needed.\n\n### Direct Cosmos DB Operations\n\nNot everything goes through the AI. Saving a time entry, loading the dashboard, and seeding sample data all talk to Cosmos DB directly — no LLM round-trip needed. The renderer calls Electron IPC handlers that invoke `saveEntry()`, `queryEntries()`, and `bulkCreateEntries()` straight from `cosmos.ts`. Seeding generates ~100 realistic entries spanning 30 days and batch-inserts them using the Cosmos DB batch API, partitioned by `userId`. The AI only gets involved when you ask a natural language question — everything else is a standard database call.\n\n---\n\n## Model Selection\n\nBy default, the app uses `gpt-4.1` via GitHub Copilot. You can change this to any [supported Copilot model](https://docs.github.com/en/copilot/reference/ai-models/supported-models) (e.g., `gpt-5`, `claude-sonnet-4.5`) by setting `COPILOT_MODEL` in your `.env`:\n\n```bash\nCOPILOT_MODEL=claude-sonnet-4.5\n```\n\n## BYOK — Bring Your Own Model (optional)\n\nIf you want to use a model outside of Copilot's lineup, you can bring your own via [BYOK](https://github.com/github/copilot-sdk/blob/main/docs/guides/setup/byok.md). You control the identity layer, the model provider, and the billing — the SDK provides the agent runtime.\n\nTwo options are supported:\n\n### Option A: Azure AI Foundry\n\nTo create and deploy a model in Azure AI Foundry, follow [Create and deploy an Azure OpenAI in Azure AI Foundry Models resource](https://learn.microsoft.com/azure/ai-foundry/openai/how-to/create-resource).\n\nUse your deployment name as `BYOK_AZURE_MODEL`.\n\n```bash\nBYOK_AZURE_ENDPOINT=https://your-resource.openai.azure.com\nBYOK_AZURE_API_KEY=your-api-key\nBYOK_AZURE_MODEL=gpt-4.1            # your deployment name\nBYOK_AZURE_API_VERSION=2024-10-21   # optional\n```\n\n\u003e **Note:** Use just the host for `BYOK_AZURE_ENDPOINT` (e.g. `https://your-resource.openai.azure.com`). Do not include `/openai/v1/` or other paths — the SDK constructs the full URL automatically.\n\n### Option B: Local model (Ollama / Foundry Local) — experimental\n\nThe app also supports local OpenAI-compatible model servers. Set these in `.env`:\n\n```bash\nBYOK_LOCAL_URL=http://localhost:11434/v1   # Ollama, or http://127.0.0.1:5272/v1 for Foundry Local\nBYOK_LOCAL_MODEL=qwen3                      # must support tool/function calling\n# BYOK_LOCAL_API_KEY=                       # optional\n```\n\n**Caveats:**\n\n- This app relies on tool/function calling — most small local models either don't support it or produce unreliable results (hallucinated data instead of calling tools).\n- Inference is significantly slower than cloud models. Timeout is auto-increased to 180s.\n- You need a capable GPU and a model that reliably handles tool calls (e.g., `qwen3` on Ollama, `qwen2.5-7b` on Foundry Local).\n- See [Ollama docs](https://docs.ollama.com/quickstart) and [Foundry Local docs](https://learn.microsoft.com/en-us/azure/ai-foundry/foundry-local/get-started) for installation and setup.\n\nWhen any BYOK vars are set, the app routes AI queries to that provider. When unset, it uses the default Copilot model.\n\n---\n\n## Cosmos DB Data Model\n\n**Container**: `timeEntries` | **Partition key**: `/userId`\n\n```json\n{\n  \"id\": \"uuid\",\n  \"userId\": \"alice\",\n  \"description\": \"API endpoint refactoring\",\n  \"project\": \"engineering\",\n  \"tag\": \"backend\",\n  \"startTime\": \"2026-02-22T09:00:00Z\",\n  \"stopTime\": \"2026-02-22T10:30:00Z\",\n  \"duration\": 5400\n}\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabhirockzz%2Fcosmosdb-copilot-sdk-time-tracker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabhirockzz%2Fcosmosdb-copilot-sdk-time-tracker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabhirockzz%2Fcosmosdb-copilot-sdk-time-tracker/lists"}