How to Override the Default Tracker File Location in Career-Ops: Complete Guide to CAREER_OPS_TRACKER

Set the CAREER_OPS_TRACKER environment variable to specify a custom path for the applications tracker file, which takes precedence over the default data/applications.md location in the santifer/career-ops repository.

Career-ops manages job application data in a markdown tracker file that defaults to data/applications.md within the repository. According to the source code in path-resolver.mjs, you can relocate this tracker to any directory—including network mounts, temporary test folders, or separate data workspaces—by configuring the CAREER_OPS_TRACKER environment variable before running any career-ops scripts.

How the Tracker Path Resolver Works

The source code in path-resolver.mjs exports two functions that centralize tracker location logic:

• resolveTrackerPath(rootDir) – Used for reading the tracker file
• resolveTrackerPathForWrite(root) – Used for writing the tracker file

Both functions check process.env.CAREER_OPS_TRACKER before falling back to the default locations. When the environment variable is present, the resolver uses that path directly; otherwise, it searches for data/applications.md or falls back to applications.md in the repository root.

Path Canonicalization for File Locking

Before returning the final path, both resolver functions invoke canonicalizeTrackerPath to convert the location into an absolute pathname. This step is essential because tracker-utils.mjs implements file-locking mechanisms that require consistent absolute paths across different processes. Without canonicalization, concurrent scripts might resolve the same logical file to different absolute paths, causing race conditions or data corruption.

Setting the CAREER_OPS_TRACKER Environment Variable

You can override the default tracker file location using shell exports, PowerShell variables, or programmatic assignment in Node.js.

Bash (Linux, macOS, WSL)

export CAREER_OPS_TRACKER="/my/custom/workspace/data/applications.md"
node merge-tracker.mjs
node set-status.mjs 42 Applied

PowerShell (Windows)

$env:CAREER_OPS_TRACKER = "C:\tmp\career-ops\applications.md"
node test-all.mjs

Node.js Scripts

process.env.CAREER_OPS_TRACKER = '/opt/ops/tracker/applications.md';
import { resolveTrackerPath } from './path-resolver.mjs';
const trackerPath = resolveTrackerPath('/opt/ops');
console.log('Using tracker:', trackerPath);

Scripts That Respect the Override

Every script that interacts with the tracker imports from path-resolver.mjs and automatically uses the overridden location:

• merge-tracker.mjs – Merges TSV data into the tracker at the custom location
• set-status.mjs – Updates row statuses in the overridden tracker file
• generate-pdf.mjs – Records PDF generation events in the specified tracker

This consistent resolution ensures that whether you are importing data, updating application statuses, or generating documents, all operations target the same tracker file defined by your CAREER_OPS_TRACKER setting.

Summary

• Set CAREER_OPS_TRACKER to override the default data/applications.md tracker location in career-ops
• The resolveTrackerPath() and resolveTrackerPathForWrite() functions in path-resolver.mjs give precedence to this environment variable
• Paths are canonicalized to absolute form to ensure consistent file locking via tracker-utils.mjs
• All career-ops scripts automatically use the custom location without requiring individual configuration changes

Frequently Asked Questions

What is the default tracker file location if CAREER_OPS_TRACKER is not set?

If the environment variable is undefined, the resolver first checks for data/applications.md in the repository root, then falls back to applications.md in the root directory. This provides backward compatibility for existing installations while allowing new deployments to specify custom locations immediately.

Can I use relative paths with CAREER_OPS_TRACKER?

Yes, relative paths are supported. The canonicalizeTrackerPath function immediately converts relative paths to absolute paths based on the current working directory, ensuring that the file-locking mechanism in tracker-utils.mjs receives a consistent absolute pathname regardless of how the path was initially specified.

Does the environment variable affect both reading and writing operations?

Yes. The resolveTrackerPath() function handles read operations while resolveTrackerPathForWrite() handles writes, and both check process.env.CAREER_OPS_TRACKER as their first priority. This ensures atomicity and consistency when multiple scripts access the tracker simultaneously.

How does career-ops prevent conflicts when multiple processes use a custom tracker location?

The tracker-utils.mjs module implements locking based on the canonical absolute path returned by the resolver. Since path-resolver.mjs ensures all processes resolve the same CAREER_OPS_TRACKER value to an identical absolute pathname, the locking mechanism works correctly even when the tracker is located on network drives or shared storage.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}