How to Use the `--chdir` Option to Launch `ds4-agent` from a Different Directory

Use ds4-agent --chdir DIR to change the working directory before the program loads model files or initializes its inference engine.

The ds4-agent command-line client from the antirez/ds4 repository provides a --chdir flag that executes a directory change immediately at startup. This eliminates the need to manually cd into target directories before launching the interactive agent, which is essential when models and configurations reside outside your current shell location.

Where --chdir Is Implemented in the Source Code

Command-Line Parsing in ds4_agent.c

The option is recognized during argument parsing in ds4_agent.c. At approximately line 677, the parser stores the provided directory path in c.chdir_path:

// From ds4_agent.c (~L677)
// --chdir DIR  Change working directory before loading assets

Directory Change Execution

After parse_options() returns the populated configuration struct, main() checks for a non-NULL cfg.chdir_path and immediately executes chdir():

// From ds4_agent.c (~L11123-L11127)
if (cfg.chdir_path) {
    if (chdir(cfg.chdir_path) == -1) {
        fprintf(stderr, "Error changing directory: %s\n", strerror(errno));
        exit(1);
    }
}

If the chdir() call fails, the program prints an error message and exits with status 1. This ensures the agent never runs with an incorrect working directory.

Practical Usage Examples

Basic: Run Agent from a Sibling Directory

When your model files live in a separate folder from your launch location:

# Current directory: /home/user/tools

# Target model directory: /home/user/models/llama-7B

ds4-agent --chdir /home/user/models/llama-7B -m llama-7B.gguf

The agent behaves exactly as if you had executed cd /home/user/models/llama-7B first, then launched without --chdir.

Combined with Backend and Thread Options

ds4-agent --chdir /mnt/data/models \
          --cuda \
          -m mixtral-8x7b-v0.1.gguf \
          -t 4

Order of operations matters: The directory change happens before any model loading, CUDA initialization, or thread pool creation. Relative paths passed to -m are resolved against the new working directory.

Using --chdir with ds4-server

The server component implements identical behavior in ds4_server.c (parsing at ~L12724, application at ~L12891):

ds4-server --chdir /opt/ds4/models --port 8080

When --chdir Is Essential

• Containerized deployments: Launch from a read-only root filesystem while loading writable models from a mounted volume
• CI/CD pipelines: Execute from build directories while referencing standardized model paths
• Shared environments: Avoid polluting shell history with cd commands when switching between model versions
• Relative path configurations: When ds4-agent reads relative paths from config files, the working directory determines their resolution

Error Handling Behavior

The implementation performs strict validation:

Scenario	Result
Directory does not exist	Error message + exit code 1
Permission denied	Error message + exit code 1
Path is a file, not directory	Error message + exit code 1
No --chdir provided	Normal startup from invocation directory

As implemented in ds4_agent.c, the error message includes the system errno description via strerror().

Summary

• --chdir DIR changes working directory before any asset loading or engine initialization
• Implementation spans parse_options() (~L677) and main() (~L11123) in ds4_agent.c
• Both ds4-agent and ds4-server support identical --chdir semantics
• Failed directory changes are fatal errors with descriptive messages and exit code 1
• Useful for containerized workflows, CI/CD, and managing relative-path configurations

Frequently Asked Questions

Does --chdir affect relative paths passed to -m?

Yes. The directory change occurs before model loading, so relative paths in -m are resolved against the new working directory. Absolute paths remain unaffected.

Can I use --chdir with environment variables?

The shell expands variables before passing to ds4-agent. Use standard shell syntax: ds4-agent --chdir "$MODEL_DIR" -m model.gguf. The source code receives the expanded path directly.

Is --chdir available in ds4-server?

Yes. ds4_server.c implements identical parsing (~L12724) and execution (~L12891) logic. The flag works with both interactive client and HTTP server binaries.

What happens if I specify a non-existent directory?

The program prints an error message including the system error description and exits with status 1. Execution stops before any model loading or initialization begins.

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