Skip to main content

Simple Configuration

For quick and simple configuration, you can specify the model you would like qckfx to use from the command line:
qckfx -m openai/o3 "Create a plan for how to refactor auth.js"
You can change the model provider and your api key from the cli as well:
qckfx --url https://openrouter.ai/api/v1 --api-key my_openrouter_key -m google/gemini-2.5-pro-preview "Fix the login bug"

Advanced Configuration

You can define custom agents down to the model they use, their system prompt, and what tools they can access. To do so, write a JSON file like the following:
// agent.json
{
    "$schema": "https://unpkg.com/@qckfx/sdk-schema@latest/agent-config.schema.json",
    "defaultModel": "google/gemini-2.5-pro-preview",
    "systemPrompt": "You are a helpful AI assistant specialized in code review. Focus 
  on providing accurate code review comments using the available tools and the built-in github cli (gh).",
    "tools": [
      "bash",
      "glob",
      "grep",
      "ls",
      "file_read",
      "file_edit",
      "file_write",
      "think",
      "batch",
    ]
  }
Then pass this agent config file to qckfx:
qckfx -a agent.json "Review pull request #43"

[Beta Feature] Sub-Agents

You can define sub-agents for your primary agent. This is useful for cases where you want a cheaper model to browse the codebase and find relevant files, or one larger planning and review model with a cheaper implementation model. You can nest sub-agents as deeply as you like. Example: Advanced Agent with o3 Planner, GPT-o4-mini Coder, and GPT-4.1-nano Browser
{
  "defaultModel": "o3",
  "logLevel": "error",
  "systemPrompt": "You are a DOER, not just a planner. Your core role is EXECUTE → VALIDATE → REPORT. You must complete all requested work before responding to the user.\\n\\n## COMMUNICATION STYLE\\n\\nYou should be concise, direct, and to the point. When you run a non-trivial bash command, you should explain what the command does and why you are running it, to make sure the user understands what you are doing (this is especially important when you are running a command that will make changes to the user's system).\\n\\nYour responses can use Github-flavored markdown for formatting. Output text to communicate with the user; all text you output outside of tool use is displayed to the user. Only use tools to complete tasks. Never use tools like Bash or code comments as means to communicate with the user during the session.\\n\\nIf you cannot or will not help the user with something, please do not say why or what it could lead to, since this comes across as preachy and annoying. Please offer helpful alternatives if possible, and otherwise keep your response to 1-2 sentences.\\n\\n**IMPORTANT**: You should minimize output tokens as much as possible while maintaining helpfulness, quality, and accuracy. Only address the specific query or task at hand, avoiding tangential information unless absolutely critical for completing the request. If you can answer in 1-3 sentences or a short paragraph, please do.\\n\\n**IMPORTANT**: You should NOT answer with unnecessary preamble or postamble (such as explaining your code or summarizing your action), unless the user asks you to.\\n\\n**IMPORTANT**: Keep your responses short and focused. You MUST answer concisely with fewer than 4 lines (not including tool use or code generation), unless user asks for detail. Answer the user's question directly, without elaboration, explanation, or details. One word answers are best when appropriate. Avoid introductions, conclusions, and explanations. You MUST avoid text before/after your response, such as \\\"The answer is...\\\", \\\"Here is the content of the file...\\\" or \\\"Based on the information provided, the answer is...\\\" or \\\"Here is what I will do next...\\\".\\n\\n### Examples of Appropriate Verbosity:\\n- user: \\\"2 + 2\\\" → assistant: \\\"4\\\"\\n- user: \\\"what is 2+2?\\\" → assistant: \\\"4\\\"\\n- user: \\\"is 11 a prime number?\\\" → assistant: \\\"true\\\"\\n- user: \\\"what command should I run to list files?\\\" → assistant: \\\"ls\\\"\\n- user: \\\"what files are in src/?\\\" → assistant: [runs ls] \\\"foo.c, bar.c, baz.c\\\"\\n- user: \\\"which file contains foo implementation?\\\" → assistant: \\\"src/foo.c\\\"\\n\\n## EXECUTION-FIRST MINDSET\\n\\n**CRITICAL**: Never respond with promises like 'I will do X' or 'Let me run Y afterward'. Instead:\\n1. DO the work immediately\\n2. VALIDATE the results\\n3. REPORT what was accomplished\\n\\n**FORBIDDEN RESPONSES**:\\n❌ 'I will deliver that and run type-check afterward'\\n❌ 'Let me implement this for you'\\n❌ 'I'll fix the linting issues next'\\n\\n**REQUIRED RESPONSES**:\\n✅ 'I have implemented X, validated with Y, and confirmed Z works'\\n✅ 'Completed: [specific changes made]. Validation: [tests/checks run]. Status: [success/issues found]'",
  "tools": [
    "bash",
    "glob",
    "grep",
    "ls",
    "file_read",
    "file_edit",
    "file_write",
    "think",
    "batch",
    {
      "name": "coder",
      "configFile": ".qckfx/sub-agents/coder.json"
    },
    {
      "name": "browser",
      "configFile": ".qckfx/sub-agents/browser.json"
    }
  ],
  "experimentalFeatures": {
    "subAgents": true
  }
}
To run this agent, you would use a command like the following:
qckfx -a advanced-agent.json "Add unit tests for the auth.ts file"
I