CHT Specialist

When to Consult Reference Files

Read the detailed reference files when the user asks about:

ODK/XLSForm Documentation

When working with XLSForm/ODK forms, consult these files based on the topic:

Guidance:

• •For CHT-specific form features (contact selector, countdown timer, cht: XPath functions): read 12-cht-extensions.md first
• •For standard ODK/XLSForm syntax: use the topic-specific files above
• •For quick lookup of common patterns: start with 13-quick-reference.md
• •When analyzing or creating a form: read 01-structure.md + relevant topic files

Assets

Overview

Expert guidance for the Community Health Toolkit (CHT), an open-source framework for building digital health applications in low-resource, offline-first settings. CHT powers applications for community health workers (CHWs), nurses, supervisors, and data managers.

Key Characteristics:

• •Offline-first architecture using CouchDB/PouchDB
• •XLSForm-based care guides and reports
• •JavaScript-based task and target configuration
• •Role-based permissions and data replication
• •SMS workflow support

Prerequisites

• •Node.js 20+ and npm
• •Docker and Docker Compose
• •cht-conf CLI tool (npm install -g cht-conf)

Quick Start

Local Development Setup

# Install cht-conf globally
npm install -g cht-conf

# Initialize a new CHT project
mkdir my-cht-app && cd my-cht-app
cht initialise-project-layout

# Deploy to local instance
cht --url=https://medic:password@localhost --accept-self-signed-certs

Docker CHT Instance

# Create directory structure
mkdir -p ~/cht/{compose,certs,upgrade-service,couchdb}

# Download compose files (check for latest version)
cd ~/cht/
curl -s -o ./compose/cht-core.yml https://staging.dev.medicmobile.org/_couch/builds_4/medic:medic:4.21.1/docker-compose/cht-core.yml
curl -s -o ./compose/cht-couchdb.yml https://staging.dev.medicmobile.org/_couch/builds_4/medic:medic:4.21.1/docker-compose/cht-couchdb.yml
curl -s -o ./upgrade-service/docker-compose.yml https://raw.githubusercontent.com/medic/cht-upgrade-service/main/docker-compose.yml

# Start CHT
cd ~/cht/upgrade-service
docker compose up --detach

Project Structure

my-cht-app/
  app_settings.json          # Main app configuration (compiled)
  app_settings/
    base_settings.json       # Base settings
    forms.json               # Form settings
    schedules.json           # SMS schedules
  contact-summary.templated.js  # Contact profile configuration
  tasks.js                   # Task definitions
  targets.js                 # Target/goal definitions
  purge.js                   # Data purging rules
  resources.json             # Icon and resource mappings
  resources/                 # Icons and media
  forms/
    app/                     # App forms (care guides)
      form_name.xlsx
      form_name.properties.json
      form_name-media/
    contact/                 # Contact creation forms
  translations/
    messages-en.properties
    messages-fr.properties

Tasks Configuration

Tasks are reminders that appear in the Tasks tab, prompting users to complete follow-up activities. See references/tasks-reference.md for complete schema, event timing, actions, and resolution logic.

Targets Configuration

Targets display key performance indicators on the Analytics tab. See references/targets-reference.md for complete schema, counting modes (idType), date filtering, and groupBy aggregation.

Contact Summary Configuration

Contact summary defines the profile page for contacts, including fields, condition cards, and context variables. See references/contact-summary-reference.md for fields schema, cards configuration, and available filters.

Forms (XLSForm)

CHT uses XLSForm format converted to ODK XForm. See references/forms-reference.md for form structure, CHT widgets, XPath functions, and properties.json configuration.

cht-conf CLI Commands

For detailed cht-conf documentation, see references/cht-conf-reference.md which covers all 42 CLI actions, CSV data import, authentication methods, and contact hierarchy management.

Common Commands

Connection Options

# Local with self-signed certs
cht --url=https://medic:password@localhost --accept-self-signed-certs

# Remote instance
cht --url=https://user:pass@your-instance.app.medicmobile.org

# Using instance shorthand
cht --instance=your-instance

# Skip server checks (offline compilation)
cht --no-check compile-app-settings

Troubleshooting

Common Issues

Task not appearing:

1. •Check appliesTo and appliesToType match your data
2. •Verify appliesIf returns true for your scenario
3. •Check event timing (days, start, end)
4. •Tasks only show for restricted users

Target not counting correctly:

1. •Verify appliesIf logic
2. •Check date filter ('reported' vs 'now')
3. •For percent, check passesIf logic
4. •Verify appliesToType matches form codes

Form not showing:

1. •Check context.expression in properties.json
2. •Verify user has required permissions
3. •Check form was uploaded successfully

Replication issues:

1. •Check user permissions and place assignment
2. •Verify contact hierarchy
3. •Check for document conflicts

Debug Commands

# Check form conversion
cht --local convert-app-forms

# Validate app settings
cht --local compile-app-settings

# Check instance connection
cht --url=https://... fetch-forms-from-server

Best Practices

Forms

• •Keep titles under 40 characters
• •Use Title Case for titles
• •Don't include patient name in form title
• •Stack radio buttons vertically
• •Use images to aid understanding
• •Group related questions logically

Tasks

• •Limit task generation to near future (60 days past, 180 days future)
• •Use unique task names
• •Provide clear resolution conditions
• •Consider performance with many contacts
• •Use appliesIf to filter early for better performance

Targets

• •Use sentence case for titles
• •Keep titles under 40-50 characters
• •Choose appropriate date filter ('reported' vs 'now')
• •Set meaningful goals
• •Use idType: 'contact' to avoid double-counting

Contact Summary

• •Group related information in cards
• •Only show actionable information
• •Use icons for important statuses
• •Keep field count reasonable for mobile

Version Compatibility

CHT Docs MCP Server

The CHT provides an official MCP (Model Context Protocol) server for AI-assisted development.

URL: https://mcp-docs.dev.medicmobile.org/mcp

Installation:

claude mcp add --transport http cht-kapa-docs https://mcp-docs.dev.medicmobile.org/mcp

External Links

• •CHT Documentation
• •CHT GitHub
• •CHT Forum
• •XLSForm Reference
• •CHT AI Tools